Self-Host Tokenfold and Connect It with Localtonet

Understand the Tokenfold proxy workflow

Tokenfold targets structured context rather than ordinary prose. Its core engine looks for mechanical structure such as repeated object keys or tabular records, then represents that structure more compactly. A uniform array of objects, for example, can be represented by naming the columns once and arranging the corresponding values into rows. The resulting content remains JSON.

The default lossless path is model-free and deterministic. Tokenfold verifies lossless transformations with an in-memory decode round trip before emitting them. It also has a never-larger guard: if a transformation does not make the content smaller, compact JSON is retained instead. This means readers should not expect every request to change. Small payloads or data without useful repeated structure may pass through without a meaningful reduction.

Exact recovery of the original JSON value is an important property, but it is not the same as proving that every model will behave identically when shown the folded representation. Model output can vary for many reasons, including provider behavior, model revisions, sampling settings, and the way a particular model interprets structured context. Validate the compressed form with representative requests from your own application before adopting it for production workloads.

Where the proxy sits in the request path

A client or agent sends its provider-shaped request to Tokenfold instead of sending it directly to the upstream LLM API. Tokenfold applies its enabled transformations, forwards the resulting request to the upstream configured at startup, receives the upstream response, and returns that response to the client.

For the workflow in this guide, the sequence is:

1. The client sends an OpenAI-compatible request to Tokenfold.
2. Tokenfold processes eligible structured content locally.
3. The proxy forwards the request to https://api.openai.com.
4. The upstream service returns its response through the proxy.
5. Tokenfold returns the response to the requesting client.

Authorization is forwarded unchanged to the upstream. That behavior is convenient for compatible clients, but it also makes the proxy a sensitive network service. Anyone who can submit requests may be able to cause authenticated upstream API activity, depending on how the client and deployment are configured. Treat remote publication as a security decision, not merely as a networking convenience.

Prerequisites and deployment decisions

Complete the Tokenfold installation and local verification before creating a public tunnel. This ordering separates application problems from networking problems. If a request fails while using 127.0.0.1, adding a tunnel cannot correct the underlying proxy, credential, or upstream configuration.

Required components

• A machine that can run the Rust Cargo toolchain and remain online while the proxy is needed.
• Network access from that machine to the selected upstream endpoint.
• An OpenAI-compatible client or agent whose API base URL can be changed.
• Valid upstream authorization configured through the normal client workflow.
• The Localtonet client installed on the same machine as Tokenfold for the loopback-target workflow documented here.
• A Localtonet device authentication token obtained from your account. Keep this token private.

The documented proxy installation uses Cargo. The available evidence does not define a complete operating-system support matrix or prescribe one universal Rust installation procedure, so install a current Rust toolchain through the supported method for your operating system. After installation, open a new terminal if necessary and verify that Cargo is available:

cargo --version

If the shell reports that cargo is not found, resolve the Rust installation or shell path before continuing. Do not substitute the tokenfold-cli, Python, Node.js, or Rust library package for tokenfold-proxy if you need the HTTP endpoint described in this guide.

Choose where the two processes will run

The simplest arrangement is to run both Tokenfold and the Localtonet client on the same host. Tokenfold listens at 127.0.0.1:8787 by default, and the Localtonet client on that host can target the loopback service directly. This preserves Tokenfold's loopback-only local exposure instead of requiring it to listen on a broader LAN interface.

If the Localtonet client runs on another device, that device cannot reach the Tokenfold host through its own 127.0.0.1. Loopback always refers to the machine making the connection. A split-host design would therefore require a separately documented reachable bind address and appropriate host firewall policy. The supplied Tokenfold evidence does not establish those bind options, so this guide does not invent them. Run both processes together unless you have verified project-specific instructions for another topology.

Install and start the Tokenfold proxy

The following process uses the proxy package documented by the project. It deliberately avoids adding undocumented flags, configuration files, environment variables, or service definitions.

The complete installation command is:

cargo install tokenfold-proxy

Start the proxy with:

tokenfold-proxy --upstream https://api.openai.com

The documented default listener is:

http://127.0.0.1:8787

OpenAI-compatible clients should use this base URL:

http://127.0.0.1:8787/v1

What startup establishes

Starting the process establishes an HTTP proxy on the loopback interface at port 8787. Loopback binding means software on the same computer can address the service, while other LAN devices cannot connect directly to that address. This is a useful default for local development and for a same-host Localtonet integration.

The command shown above configures https://api.openai.com as the upstream. Do not silently substitute another upstream and assume complete compatibility. If you use another provider or gateway, first verify that it accepts the request shapes and authorization behavior produced by your chosen client. The project describes the proxy as provider-neutral by design, but concrete provider compatibility still depends on the upstream interface.

Configure an OpenAI-compatible client

A compatible client usually has a setting named API base URL, endpoint, server URL, or a similar term. Change that setting from the upstream provider's direct base URL to:

http://127.0.0.1:8787/v1

Do not change the model identifier, request structure, or authorization configuration merely to test the proxy. Keeping those values aligned with a previously working direct-upstream configuration makes troubleshooting easier. The meaningful initial change is the base URL.

The client then sends the same provider-shaped request to Tokenfold. The proxy processes eligible structured context and forwards the request to the upstream selected by the --upstream argument. Authorization is forwarded unchanged.

Use a representative test request

A minimal conversational request may confirm connectivity, but it may not exercise Tokenfold's main purpose. For meaningful evaluation, use a request that resembles your real workload and contains structured data such as:

• A repeated array of JSON objects.
• A substantial set of tool definitions.
• Structured retrieval results used by a RAG workflow.
• Tool-calling agent context containing repeated schemas or logs.

Very small examples can remain unchanged because the never-larger guard avoids transformations that do not save space. A successful request with no visible reduction is therefore not necessarily an installation failure.

Keep lossy behavior separate from the first deployment

Tokenfold also describes opt-in, recoverable pruning for heterogeneous array feeds. Dropped rows remain fetchable, but this is distinct from the default lossless structural folding path. Begin with the lossless workflow, establish correctness with representative application tests, and evaluate optional pruning separately.

The project's schema_compaction behavior is also not enabled by presets and is not reversible because it truncates example arrays. Do not treat it as equivalent to the exact recovery guarantees of the default lossless transformations.

Verify Tokenfold locally before tunneling

Local verification should answer three separate questions: is the process listening, can the client reach it, and can an authenticated request complete through the configured upstream? Test them in that order.

1. Confirm that the process remains running

Keep the terminal containing tokenfold-proxy open. An immediate process exit indicates a local startup problem. Read the displayed error rather than moving on to Localtonet. Common local causes include an unavailable executable, a conflicting listener on port 8787, or an invalid startup argument.

2. Check local HTTP reachability

From a second terminal on the same machine, make a verbose HTTP request to the local listener:

curl -v http://127.0.0.1:8787/

This request is only a transport check. The root path is not the documented OpenAI-compatible API base, so an HTTP error status or route-not-found response does not by itself indicate a broken proxy. The useful distinction is whether an HTTP connection is established. A connection-refused error means nothing is listening at the expected address and port.

If curl is unavailable on your operating system, use an equivalent local HTTP client. Do not include a real Authorization header in a command that could be copied into shell history or support messages.

3. Send a normal request through the compatible client

Set the client's base URL to http://127.0.0.1:8787/v1, retain its valid upstream authorization, and submit a request that already works when sent directly to the provider. A successful response confirms the complete local path from client to Tokenfold, from Tokenfold to the upstream, and back.

4. Validate application behavior

Repeat the test using representative structured context. Check the response content, expected tool calls, application parsing, retries, and error handling. If your application depends on exact task outcomes, compare direct and proxied runs under controlled settings. Do not infer production suitability from a single connectivity test.

5. Establish a local baseline

Record the client configuration that worked, excluding credentials. Note the upstream URL, local base URL, model identifier, and the type of request used. This baseline becomes the reference point for remote troubleshooting. If the same request works locally but fails through the public URL, the fault is likely in remote configuration, tunnel state, or access policy rather than the Tokenfold installation itself.

Connect the verified proxy with a Localtonet HTTP tunnel

After local verification, our HTTP tunnel can give the loopback service a public HTTPS address. The Localtonet client establishes an outbound connection to a relay server, so this workflow does not require inbound router port forwarding, a public IP address, firewall changes, or VPN setup.

Keep the Localtonet client on the same machine as Tokenfold. The tunnel's local target is 127.0.0.1 on port 8787. Creating a tunnel does not start it. You must start the tunnel after configuration, and it remains available only while the selected client is connected and the tunnel is running.

HTTP tunnels support Random Sub Domain, Custom Sub Domain, and Custom Domain process types. Each serves the same target content at a public HTTPS address. Availability can vary, and custom-domain DNS details should be checked against the current dashboard and documentation rather than inferred.

You can review the current workflow in our Localtonet HTTP tunnel documentation.

Configure the remote client

Once the tunnel is running, take the public HTTPS address assigned to the HTTP tunnel and append the same /v1https://assigned-host.example, the remote client's conceptual base URL becomes:

https://assigned-host.example/v1

The hostname above is intentionally illustrative, not a real Localtonet endpoint. Always use the exact public URL assigned to your tunnel.

Test the remote client with the same request used for the local baseline. Preserve its upstream authorization configuration. If the request succeeds locally but not remotely, first confirm that all three required processes are available: Tokenfold is running, the Localtonet client is connected, and the HTTP tunnel is started.

Secure the remote proxy workflow

Publishing an LLM proxy is more sensitive than publishing a static development page. Requests can contain internal prompts, schemas, logs, retrieval results, tool arguments, and upstream credentials. A remote caller may also create billable upstream activity. Plan security around the entire path rather than focusing only on whether the public address uses HTTPS.

Protect upstream authorization

Tokenfold forwards Authorization headers unchanged. Never put a real token in a public example, tunnel name, URL query string, issue report, screenshot, or shared shell transcript. Prefer the secure credential mechanism supported by the calling client. If a credential is accidentally disclosed, revoke or rotate it through the upstream provider rather than merely changing the public tunnel URL.

Use narrowly scoped credentials where possible

If the upstream provider supports restricted projects, quotas, separate service identities, or limited credentials, use them for this proxy workflow. Exact capabilities vary by provider and account, so verify them with the provider rather than assuming that every API key has scope controls.

Separate users and environments

Avoid sharing one exposed development proxy across unrelated users or applications. Separate development, testing, and production credentials. A tunnel created for a short evaluation should not silently become a permanent production endpoint without an access review, monitoring plan, and operational owner.

Minimize exposure time

Start the tunnel when a remote agent needs it and stop it when the task is complete. Stopping the tunnel removes public reachability without requiring you to uninstall Tokenfold. Stop the local proxy as well if it is not needed by local applications.

Review the data being compressed

Local compression means the folding step occurs inside the operator-controlled environment, but the resulting request is still forwarded to the selected upstream provider. Tokenfold is not a promise that application data never leaves the machine. Apply the upstream provider's data-handling policy to the transformed request just as you would to an uncompressed request.

Do not confuse tunneling with a VPN

An HTTP tunnel publishes the configured local HTTP target. It does not create a general private network between devices. Localtonet VPN Manager is our separate private mesh VPN capability. Use the HTTP tunnel for this narrowly defined proxy endpoint rather than describing it as VPN access.

Operate and maintain the deployment

The remote endpoint depends on multiple components, so routine operation should account for each one. A tunnel can be correctly configured yet unavailable because the Tokenfold process stopped. Tokenfold can also be healthy locally while the selected Localtonet device is disconnected.

Recommended startup order

1. Start Tokenfold with the intended upstream.
2. Verify the local listener at 127.0.0.1:8787.
3. Send a valid local client request through http://127.0.0.1:8787/v1.
4. Start the Localtonet client and confirm that the correct device is connected.
5. Start the HTTP tunnel.
6. Run the remote baseline request against the assigned public URL with /v1.

This sequence prevents the public endpoint from being treated as the first diagnostic surface. It also reduces the chance of publishing an unverified service.

Recommended shutdown order

1. Stop remote clients from submitting new requests.
2. Stop the Localtonet tunnel.
3. Stop the Tokenfold process when it is no longer needed locally.
4. Delete the tunnel if the configuration will not be reused.

Process supervision

For longer-running deployments, use the process-management facilities appropriate to your operating system to keep Tokenfold and the Localtonet client available. The supplied Tokenfold evidence does not define a canonical system service file, container image, Docker Compose file, Windows service configuration, or background-run command for this exact workflow. Avoid copying an invented service definition. Whatever supervisor you choose should run the same verified startup command and should not expose credentials in world-readable configuration.

Updates and regression testing

Before changing the Tokenfold version, preserve a credential-free record of the working command, base URLs, client settings, and representative test cases. After updating, repeat local transport, authenticated upstream, structured-workload, and remote-tunnel tests. Review changes before relying on previous compression or compatibility behavior.

Tokenfold has separate packages for its proxy, CLI, libraries, and core engine. Confirm that an update procedure applies to tokenfold-proxy rather than assuming that updating the Python or Node.js package also updates the installed proxy binary.

Monitoring boundaries

Monitor the states you can verify without logging secrets: whether the local process is running, whether port 8787 accepts a connection, whether the Localtonet device is connected, whether the tunnel is running, and whether a safe synthetic request succeeds. Redact Authorization headers and sensitive request bodies from diagnostics.

Localtonet also has platform-wide Token/Tunnel webhooks for Connected and Disconnected state changes within a selected Token Group. Those are operational status events, not request logs and not Tokenfold application events. They are distinct from File Server file-event webhooks and should not be represented as monitoring the content or success of individual LLM requests.

Troubleshoot installation, proxy, and tunnel problems

Diagnose the workflow from the inside out. Start with the executable, then the local listener, then the upstream request, and finally the Localtonet path. This avoids attributing an application error to the tunnel or a disconnected tunnel to Tokenfold.

Use a four-boundary diagnostic

When the cause remains unclear, test each boundary independently:

1. Executable boundary: Does tokenfold-proxy start and remain running?
2. Local HTTP boundary: Can the same host establish an HTTP connection to 127.0.0.1:8787?
3. Upstream boundary: Can a properly configured compatible client complete a request through the local /v1 base URL?
4. Remote boundary: Can the same request complete through the assigned public HTTPS address with /v1 appended?

The first failing boundary identifies where to focus. For example, if the upstream request works locally but the remote boundary fails, reinstalling Tokenfold is unlikely to help. Check tunnel state, selected device, target address, and remote client URL instead.

Frequently asked questions