Stable AI Sandbox Ingress with Localtonet

Why ephemeral sandboxes need a stable ingress layer

An AI agent sandbox is often a disposable execution environment rather than a conventional long-running application server. A controller may create it only after a task arrives, select an image and resource profile, populate a workspace, execute tools, pause the environment, restore it later, and finally destroy it. Its internal address, process identity, runtime credentials, and listening ports may be valid only for that particular instance.

External systems operate on a different timeline. A webhook provider, browser, automation service, or collaborating agent normally needs an address that can be configured before a particular sandbox exists. It may retry requests minutes later, retain a callback URL for the duration of a job, or deliver an event after the original workspace has been replaced. Making the public endpoint as ephemeral as the container turns every lifecycle event into a networking event.

The stable-gateway pattern separates these concerns. A gateway runs on the host, or on another machine that can reach the sandbox network. The gateway owns the durable HTTP listening address, authenticates requests, validates their intended destination, looks up the current sandbox instance, and forwards only approved traffic. Sandboxes register and unregister with this gateway as they transition through their lifecycles.

With Localtonet, our client connects outward to a Localtonet relay server and exposes that stable gateway through one public HTTPS address. The tunnel points to the gateway's local IP address and port, not to an individual sandbox. This avoids requiring inbound router port forwarding, firewall changes, VPN setup, or a public IP address for the gateway host.

Separate the data plane from the control plane

It helps to model the design as two related planes. The data plane carries an accepted HTTP request from the public address to the gateway and then to the selected sandbox service. The control plane creates sandboxes, records their identities, performs readiness checks, adds or removes routes, rotates credentials, and decides whether a stopped environment may be resumed.

Do not let an arbitrary incoming request control the sandbox runtime directly. For example, a path parameter should not become an unchecked container name, process command, hostname, or port. The gateway should resolve a validated logical identifier through a registry populated by the trusted controller. The registry entry, not user input, supplies the internal destination.

Design a routing contract that survives instance replacement

A dependable route identifies a logical workspace, task, or session rather than a container's transient network address. Suppose an integration sends a request for workspace ws_7f3. The gateway should use that identifier to locate an active registry record. That record can point to whichever sandbox currently owns the workspace. If the sandbox is restored into a new runtime instance, the controller updates the registry without changing the external route.

Path-based routing is usually straightforward for a single public hostname. A conceptual route might use /sandboxes/{workspace-id}/.... Another design can put the workspace identifier in a signed request claim while keeping the public path generic. The correct choice depends on the client, but the identifier must be opaque, validated, and authorized. It should not reveal filesystem paths, internal hostnames, sequential database keys, or credentials.

Minimum registry record

The implementation technology is up to the operator, but each active route generally needs enough information to answer five questions: which logical workspace is being requested, which runtime instance currently owns it, where that instance is reachable, whether it is ready, and when the registration expires. The following record is an illustrative application-level contract, not a Localtonet configuration:

{
  "workspaceId": "ws_7f3",
  "instanceId": "runtime_92b",
  "target": {
    "scheme": "http",
    "host": "sandbox-network-name",
    "port": 0
  },
  "status": "ready",
  "generation": 12,
  "expiresAt": "application-defined timestamp"
}

The value 0 is intentionally not a usable port. Replace it with the actual port on which your sandbox service listens. That value must come from your sandbox application or orchestrator documentation. There is no universal AI sandbox port, and Localtonet does not assign the internal service port.

A generation number prevents an older instance from overwriting the registration of a newer replacement. If generation 12 has become active, a delayed shutdown event from generation 11 must not delete generation 12's route. Compare both the logical workspace identifier and instance generation during updates and removal.

Constrain what the proxy may forward

The gateway should not behave as an open forward proxy. Permit destinations only from the trusted registry, and restrict those destinations to the network range, service identity, and ports intended for sandbox traffic. Normalize paths before applying policy. Reject attempts to use encoded traversal sequences, absolute URLs, alternate schemes, unexpected host headers, or redirect behavior to reach an unapproved service.

Decide deliberately which headers cross the boundary. Strip hop-by-hop headers and any client-supplied identity headers that the gateway itself is responsible for generating. If the sandbox needs caller identity, send a narrowly scoped, integrity-protected assertion rather than forwarding a reusable platform credential. Also define request-body limits, response-size limits, streaming behavior, and timeouts that match the workload.

Coordinate registration with the sandbox lifecycle

A route should exist only when the corresponding runtime is ready to serve it. Registering at container creation time is too early because image startup, dependency initialization, repository checkout, migrations, or an agent-side server may still be incomplete. Removing a route only after a process has disappeared is too late because the gateway may continue sending requests into a failing connection.

Use explicit lifecycle states and make route updates part of the controller's transition logic. A practical flow is shown below. These are architecture steps for the gateway and sandbox controller, not Localtonet dashboard steps.

Use leases instead of assuming cleanup always runs

Graceful shutdown hooks are useful, but they are not sufficient. A sandbox host can crash, a process can be killed, or a network partition can prevent the controller from sending its unregister request. A registration lease gives every route a bounded lifetime unless the legitimate owner renews it.

The lease duration and renewal interval depend on startup cost, traffic patterns, and how quickly stale access must disappear. There is no universal value. The important property is that route expiry is automatic and that renewal verifies both runtime identity and generation. The gateway should fail closed when a lease expires.

Handle replacement without a routing gap

If a workspace moves to a replacement sandbox, prepare and verify the new instance before switching the active registry pointer. The update should be atomic. Existing requests may finish on the previous instance if the application supports draining, while new requests go to the replacement. Do not let two instances accept mutating operations for the same logical workspace unless the application is explicitly designed for concurrent writers.

Keep snapshots, route state, and secrets in the right boundaries

Filesystem snapshots can preserve useful workspace state, but they do not automatically preserve a valid network identity. A restored sandbox may receive a new runtime identifier, internal address, process state, or service credential. Treat restoration as creation of a new runtime generation, even when its files look exactly like those of the previous instance.

The route registry belongs outside the sandbox filesystem. If the registry is captured inside a snapshot, restoring that snapshot can resurrect stale addresses and ownership claims. The gateway's trusted control plane should remain authoritative, and a restored runtime should complete readiness checks before obtaining a fresh registration.

Avoid baking secrets into reusable images

Sandbox images and snapshots are likely to be reused. Do not place Localtonet device tokens, gateway administration credentials, webhook secrets, user credentials, or broad cloud keys inside them. Deliver narrowly scoped, short-lived credentials at runtime where the sandbox platform supports that model, and revoke them when the instance terminates.

The Localtonet client should normally run with the stable gateway host, not inside every disposable sandbox. This keeps the device token and tunnel lifecycle outside untrusted or frequently rebuilt workspaces. It also ensures that replacing an agent image does not require recreating the public ingress configuration.

Secure the gateway as the public trust boundary

A public URL is an ingress path, not an authorization policy. The gateway must decide who can reach a workspace and which operation each identity may perform. This matters especially for agent sandboxes because their services may expose command execution, file access, package installation, browser automation, development previews, or tools with outbound network access.

Start by defining the smallest public API that the integration actually needs. If an external system only delivers job events, expose a narrow event endpoint rather than the sandbox's entire development server. If users need a preview, isolate preview routes from administrative routes. Management operations such as creating, resuming, terminating, or snapshotting a sandbox should use a separately protected control-plane interface.

Authenticate before route lookup reveals information

Validate the caller before returning route-specific detail. A generic authorization response prevents an attacker from discovering which workspace identifiers exist. Bind credentials to a tenant, workspace, operation, and expiration where practical. A credential accepted for a read-only preview should not authorize command execution or lifecycle management.

Apply least privilege at multiple layers

• Allow each external identity to access only its assigned workspaces and operations.
• Allow the gateway to connect only to approved sandbox service destinations.
• Prevent sandboxes from reaching the gateway's administration interface.
• Keep the registry update interface private and authenticate the sandbox controller.
• Restrict sandbox outbound access according to the task rather than enabling unrestricted egress by default.
• Use separate credentials for external callers, gateway-to-sandbox requests, and controller-to-registry updates.
• Record security-relevant lifecycle and routing events without logging secrets or sensitive request bodies.

Protect request processing

The gateway should define request size limits, header limits, acceptable content types, timeouts, concurrency limits, and rate controls. Long-running agent work should usually return a job identifier and continue asynchronously rather than holding an unbounded public HTTP request open. If streaming is required, test how the gateway and sandbox handle disconnects, backpressure, and partial output.

Treat uploaded archives, repositories, prompts, and tool arguments as untrusted content. A sandbox limits part of the impact, but it does not replace application validation. Ensure that one workspace cannot mount, address, or infer another workspace's files or service. Keep host management sockets and sensitive host paths outside sandbox reach.

Log the decisions that matter

Useful audit events include authentication outcome, logical workspace identity, resolved runtime generation, policy decision, request class, response status, registration changes, lease expiry, and sandbox lifecycle transitions. Avoid recording access tokens, Localtonet device tokens, private endpoints, raw credentials, or sensitive prompts. Correlation identifiers should be random and safe to share with operators.

Monitor the gateway separately from sandbox applications. A healthy gateway with no valid routes is different from a failed gateway. Likewise, a running tunnel does not prove that the gateway can reach a particular sandbox. Build checks for each boundary rather than relying on one end-to-end status indicator.

Design inbound events and outbound callbacks separately

Inbound ingress and outbound callbacks solve different problems. Inbound ingress lets an external system send a request through the public Localtonet URL to the gateway. An outbound callback begins inside the application and connects to an external destination. The callback usually does not need to travel backward through the same tunnel.

For inbound events, configure the external service with a gateway route that does not depend on a container address. The gateway authenticates the event, verifies its signature if the provider supports signing, determines the authorized workspace, and either forwards it to a ready sandbox or stores it in an application-managed queue. A queue can absorb brief startup delays, but it must have bounded retention, deduplication, tenant isolation, and a clear failure policy.

For outbound callbacks, let the sandbox or a trusted callback worker make an outbound connection according to your egress policy. Prefer a callback worker outside the sandbox when delivery must survive sandbox termination. The sandbox can submit a result to that worker, which then handles retries and records delivery status.

Make event processing idempotent

External services often retry when delivery times out or returns an error. A gateway may also lose its client connection after the sandbox has already accepted work. Assign or preserve an event identifier and make processing idempotent. The same event should not create duplicate work merely because it was delivered twice.

Idempotency records should live outside a disposable sandbox if they must survive replacement or restoration. Define their retention based on the provider's retry window and your application requirements. Do not assume a filesystem snapshot contains the latest deduplication state.

Prevent callback-based data leakage

A compromised sandbox may try to send data to an attacker-controlled address. Validate callback destinations in the trusted control plane, use an allowlist when the workflow permits it, and avoid giving the sandbox a broad credential that can modify callback configuration. If users may supply callback URLs, protect against server-side request forgery by blocking internal addresses, metadata endpoints, unsupported schemes, redirect escapes, and ambiguous DNS behavior.

Verify the complete workflow locally before public exposure

Test from the same machine that will run the Localtonet client, because that machine must be able to reach the gateway's configured local target. A service that responds inside a sandbox does not prove that the host-side gateway can reach it. Likewise, a gateway process that is listening does not prove its registry, authorization, and proxy path work.

The exact commands depend on the gateway implementation and operating system. The following requests use illustrative paths. Replace the port, paths, identifiers, and credentials with values defined by your application. Do not copy placeholder values into production configuration.

1. Verify the gateway listener

curl -i http://127.0.0.1:<gateway-port>/health

This check should confirm that the gateway process is running. It should not report the whole system as healthy merely because its HTTP listener is open. Consider separate readiness output for dependencies such as the route registry.

2. Verify a registered sandbox through the gateway

curl -i \
  -H "Authorization: Bearer <short-lived-test-credential>" \
  http://127.0.0.1:<gateway-port>/sandboxes/<workspace-id>/ready

This test exercises authentication, workspace authorization, registry lookup, internal connectivity, and the sandbox service. Keep real credentials out of shell history and logs. Use a test identity limited to the test workspace.

3. Test denied and stale routes

Attempt access with no credential, with a credential for another workspace, and after removing the route. All three cases should fail without revealing the internal destination. Stop the sandbox unexpectedly and verify that lease expiry removes the route even when graceful cleanup does not run.

4. Test replacement behavior

Start a second runtime generation for the same logical workspace, verify it, and atomically switch the registry. Then deliver a delayed unregister event from the old instance. The current route must remain intact. This test catches generation-handling errors that can appear only during concurrent replacement.

5. Test snapshot restoration

Restore a workspace into a new runtime and confirm that it cannot receive traffic until it obtains a new runtime identity, passes readiness, and registers a fresh destination. Verify that old credentials and old route metadata were not revived from the snapshot.

6. Test request boundaries

Send an oversized request, an unsupported content type, an invalid path, a malformed workspace identifier, an absolute target URL, and a request that exceeds the configured timeout. Confirm that the gateway rejects each case predictably and does not forward it to another internal service.

Expose the stable gateway with a Localtonet HTTP tunnel

Configure Localtonet only after the gateway works locally. The tunnel's local target should be the stable gateway address and port. It should not point directly to a sandbox address that can disappear or be reassigned.

HTTP tunnels support a Random Sub Domain, Custom Sub Domain, or Custom Domain process type. Each serves the configured content at a public HTTPS address. Available options may vary by current plan or dashboard configuration, so use the choices shown in your account. If using a custom domain, verify the current DNS requirements in our documentation before changing DNS records.

For the current dashboard workflow and field names, consult our Localtonet HTTP tunnel documentation. Documentation supplements the architecture described here, but the essential target remains the same: one stable gateway, not one tunnel per disposable sandbox.

Verify from outside the local network

After starting the tunnel, test from a network that does not have direct access to the gateway host. First call a safe gateway health endpoint if one is intentionally public. Then send an authenticated request to a test workspace. Finally, repeat the negative tests for missing credentials, unauthorized workspace identities, expired routes, and malformed paths.

Do not treat a successful public health response as proof that sandbox routing works. A complete test must traverse the public HTTPS address, Localtonet tunnel, local gateway, registry lookup, authorization policy, internal sandbox connection, and application response.

Operate, monitor, and clean up the ingress path

Stable ingress reduces endpoint churn, but it also makes the gateway important infrastructure. Plan its restart behavior, dependency failures, credential rotation, logging, and upgrades. Persist only the control-plane state that must survive restart, and reconstruct active route eligibility from authoritative controller information rather than trusting stale in-memory mappings.

Monitor each boundary independently

Use a deliberate termination sequence

When a workspace finishes, mark its route as draining before stopping the sandbox. Reject new jobs, complete or cancel accepted work according to application policy, remove the exact route generation, revoke runtime credentials, and then terminate the instance. Clean temporary files and callback state according to retention requirements.

Do not automatically stop the shared Localtonet tunnel merely because one sandbox ends. The tunnel belongs to the gateway lifecycle and may serve other active workspaces. Stop it only when the shared public ingress should become unavailable. This separation is the main operational benefit of the design.

Troubleshoot from the inside out

If the public request fails, begin with the sandbox service and move outward. Confirm that the service is listening on the intended interface and port. From the gateway host, test the sandbox destination recorded in the registry. Test the same request through the gateway's local address. Then verify that the selected Localtonet client is connected, the HTTP tunnel is running, and its local target matches the gateway.

A connection refusal usually indicates that nothing is listening at the target or the address is wrong. A timeout can indicate network isolation, an unresponsive application, or an overly long operation. A not-found response may mean the registry entry is absent or expired. An authorization failure should be investigated through policy and identity logs without weakening access controls merely to make the request succeed.

Plan gateway availability honestly

One gateway simplifies routing, but one process can also become a single failure point. The appropriate redundancy model depends on the registry, session behavior, local network, and deployment platform. This guide does not prescribe a universal high-availability topology because those details are not defined by Localtonet and vary significantly across environments.

At minimum, supervise the gateway process, make startup deterministic, back up required control-plane data, and test recovery. If multiple gateway instances share traffic, they need a consistent route registry and authorization policy. Avoid storing essential routing ownership only in one process's memory.

Frequently asked questions