Isolate AI Agents and Connect Them Safely

Why tool-using AI agents need an isolation boundary

A conversational model that only returns text has a relatively narrow interface. A tool-using agent is different. Depending on the runtime and permissions selected by its operator, it may be able to open files, invoke a shell, install dependencies, clone repositories, run builds, start network listeners, call external APIs, or continue a task without constant supervision. The correct security question is therefore not only whether the model is trustworthy. It is also what the surrounding process can reach when instructions, generated commands, dependencies, or tool results are wrong.

Running that process directly on a daily workstation can collapse several trust boundaries into one. The agent may execute beside browser profiles, SSH keys, source repositories, cloud credentials, password-manager integrations, personal documents, cached package credentials, local development databases, and authenticated command-line tools. Even when the agent is intended to touch only one project directory, operating-system permissions or broadly scoped credentials may give it substantially more reach.

Isolation reduces this exposure by placing the agent in a separate execution environment with its own filesystem, accounts, credentials, network policy, and lifecycle. That environment could be a dedicated virtual machine, a disposable sandbox, a container running on a separate host, a spare computer, or a cloud machine. The specific technology matters, but the more important architectural principle is that the agent should not share an administrative context with sensitive personal or production assets.

Isolation is not a claim that an agent can never fail or be manipulated. It is a way to constrain the consequences. If the environment contains only a temporary repository checkout, a narrowly scoped token, and a limited service account, then an accidental destructive command or malicious instruction embedded in external content has fewer valuable targets.

Build a threat model before choosing the host

Start by describing the agent as a process with inputs, tools, identities, data, and network connections. Avoid relying on a label such as “sandboxed” without identifying the actual boundary. Different environments can isolate filesystems, processes, kernels, networks, or hardware to different degrees. The right choice depends on the impact of a failure and the trustworthiness of the code and data involved.

Instructions can arrive through more than the prompt box

An agent may consume repository files, issue descriptions, web pages, email, documents, logs, test output, package metadata, and tool responses. Any of those inputs can contain misleading or hostile instructions. A model might treat untrusted content as a task directive even when the operator did not intend it to do so. Isolation and least privilege remain necessary because filtering prompts alone does not provide a complete security boundary.

Generated commands can be incorrect without being malicious

Security planning must account for ordinary mistakes. A malformed cleanup command can delete the wrong path. A package installer can execute lifecycle scripts. A build can consume excessive CPU, memory, disk, or network capacity. A development server can bind more broadly than expected. An agent can also expose data through logs or error messages. The environment should be able to tolerate these failures without placing unrelated systems at risk.

Credentials expand the blast radius

A machine with a broad cloud credential or a repository token that can access an entire organization is not meaningfully low privilege merely because it is disposable. The token may allow the process to affect systems outside the sandbox. Use separate service identities, choose the smallest practical scope, set expiration where the credential system supports it, and revoke credentials when the task ends or the environment is discarded.

A reachable interface creates a separate trust boundary

The agent may start a dashboard, webhook receiver, API, model endpoint, development preview, or MCP-related service. Publishing that listener makes it reachable beyond the isolated machine. The tunnel controls connectivity to the chosen local target, but application authorization remains the responsibility of the service. A public address should not be treated as secret merely because it is difficult to guess.

A safer architecture for remote AI agent workloads

A practical design has four distinct layers: the operator, the isolated execution host, the narrowly scoped application service, and the connectivity layer. Keeping these roles separate makes it easier to reason about permissions and determine what must be shut down after a task.

1. The operator controls policy, not every command

The operator decides what the agent may work on, which credentials it receives, what data enters the environment, and which output leaves it. Human approval should be required for high-impact actions such as production deployment, irreversible deletion, permission changes, credential creation, or publication of sensitive artifacts. The exact approval mechanism depends on the selected agent platform, so verify that platform's documented controls rather than assuming a confirmation prompt provides a hard security boundary.

2. The isolated host contains agent execution

The host should have a dedicated operating-system identity and only the packages needed by the workload. It should not inherit workstation credentials or automatically synchronize personal folders. If the job is temporary, a reproducible disposable environment is usually easier to clean up. If the job must remain active for days or weeks, a persistent machine may be appropriate, but it requires patching, monitoring, storage management, and a deliberate shutdown process.

3. The application endpoint offers a narrow contract

Prefer an endpoint that accepts a defined set of requests and returns constrained responses. For example, a web dashboard can expose task status, an API can submit approved job types, or a webhook can accept signed events. Avoid a generic endpoint that accepts arbitrary shell commands merely for convenience. Validate inputs, cap request and payload sizes where the application supports it, and prevent error responses from revealing secrets or internal paths.

4. The tunnel publishes the selected service

The Localtonet client runs on the isolated machine, or on another device that can reach its service. The client establishes an outbound connection to a Localtonet relay server. The resulting tunnel provides a public URL or a public host and port, depending on the tunnel type. This avoids inbound router port forwarding, firewall changes, VPN setup, and the requirement for a public IP address.

The tunnel is available only while the selected client or device is connected and the tunnel is running. Creating a tunnel does not start it. This lifecycle distinction is useful for agent workloads because public reachability can be limited to the period when the endpoint is intentionally in use.

Choose HTTP or raw TCP according to the service

Use the narrowest protocol that matches the application. Do not select TCP merely to avoid configuring HTTP authentication, and do not assume every agent runtime uses the same transport. Confirm whether the service speaks HTTP, raw TCP, or a documented MCP transport before creating the tunnel.

Prerequisites and decisions to make first

This architecture is intentionally independent of a particular agent framework or compute vendor. Exact installation commands, package names, default ports, environment variables, and service paths differ among runtimes. Use the official instructions for the agent software you select, and do not copy values from an unrelated project. Before installing anything, document the following decisions.

• Isolation host: a separate virtual machine, container host, spare device, or cloud computer that you are authorized to administer.
• Agent runtime: the specific software responsible for accepting tasks and using tools.
• Working data: the repositories, files, test fixtures, and generated artifacts the agent needs.
• Credential set: separately issued, least-privilege credentials for only the required systems.
• Local endpoint: the documented IP address, port, and protocol used by the agent interface.
• Remote audience: the people or systems that should be permitted to call the endpoint.
• Application authentication: the method by which the service verifies that audience.
• Retention plan: what must be saved, what may be deleted, and when the host should be rebuilt.
• Localtonet client: installed on the isolated host or on a device with network reachability to the endpoint.
• Localtonet device token and relay selection: obtained from the current dashboard rather than copied into documentation, logs, scripts, or source control.

Decide whether the environment is persistent or disposable. A persistent environment is suitable when the agent must keep a large working tree, local indexes, or long-running processes. It also accumulates state and therefore requires maintenance. A disposable environment offers a clean boundary between jobs, but important artifacts must be exported before destruction. Neither model removes the need for least privilege.

Also decide where the Localtonet client belongs. Running it on the isolated host creates a simple boundary because the client can target a service on that same machine. Running it on a separate gateway is possible when that gateway can reach the service, but the gateway then becomes part of the trusted path. Do not broaden network access merely to make the tunnel configuration easier.

Build the isolated agent environment

The following workflow is platform-neutral because agent products and operating systems use different commands. It focuses on controls that should be implemented regardless of the chosen runtime. Record the exact commands and package versions in your own deployment configuration so the machine can be reproduced and reviewed.

Limit outbound access where practical

An outbound-only connectivity design means the published service does not require an inbound router rule or public address. It does not mean the agent should have unrestricted outbound internet access. If your environment supports egress controls, limit destinations to the package registries, source-control hosts, model APIs, artifact stores, and Localtonet connectivity required by the workload. Allow for update and certificate-validation requirements documented by the software you use.

Egress rules require careful testing because destinations and content-delivery networks can change. A broken allowlist can look like an agent failure, while an overly broad rule weakens the intended boundary. Keep the policy documented and review connection failures before opening large address ranges.

Keep sensitive values out of prompts and logs

A secret available to the process can potentially appear in command output, generated files, crash reports, or agent context. Prefer credential helpers, environment-specific secret stores, or injected runtime values over plaintext files where the platform supports them. Redact logs before sharing them. Do not ask the agent to print all environment variables as a debugging shortcut.

Publish only the required endpoint with Localtonet

Once the service works locally, add remote access as a separate step. This order matters. It prevents tunnel troubleshooting from being confused with an application that never started, is listening on a different port, or rejects requests because authentication is incomplete.

The supported Localtonet tunnel categories include HTTP/s, TCP, UDP, TLS, combined UDP/TCP, File Server, Proxy Server, and VPN Manager. An agent web interface or HTTP API should normally use an HTTP tunnel. A non-HTTP agent protocol that requires a raw TCP stream should use a TCP tunnel. This guide does not recommend publishing files, creating a proxy exit node, or building a mesh VPN for a use case that only requires one agent endpoint.

HTTP tunnels can use the currently supported process types: Random Sub Domain, Custom Sub Domain, or Custom Domain. These options serve the configured content at a public HTTPS address. Availability and domain setup requirements may vary, so check the current dashboard and documentation before depending on a particular naming option. Exact custom-domain DNS instructions are intentionally not included here because they must be verified against the current configuration workflow.

Verify both connectivity and containment

A successful public response proves only that traffic can reach the service. A complete verification checks the local service, the public path, application authorization, host permissions, credential scope, and shutdown behavior.

Test the local endpoint first

From the isolated host, send a normal request using a browser or protocol-appropriate client. Confirm that it reaches the intended process and not a different service using the same port. Repeat the test without credentials or with an unauthorized identity. The service should reject that request according to its documented behavior.

Test through the public address

Start the tunnel and connect from a device outside the isolated host. For an HTTP endpoint, confirm that the assigned URL reaches the expected interface. For raw TCP, use the service's proper client with the assigned host and port. Do not treat a generic successful socket connection as proof that the application protocol and authentication work correctly.

Test negative cases

• Send a request without application credentials and verify that it is denied.
• Attempt an operation outside the agent's intended role and verify that authorization blocks it.
• Ask the agent to access an unrelated directory and confirm that operating-system permissions prevent it.
• Use the source-control identity against an unrelated repository and confirm that its scope does not permit access.
• Stop the tunnel and verify that the public endpoint is no longer available.
• Stop or disconnect the Localtonet client and verify that the tunnel becomes unavailable.
• Restart the environment and confirm that only intentionally persistent data and services return.

Review what the agent can discover

Inspect the runtime account's readable files, process environment, mounted volumes, network routes, command history, and configured tools. Remove leftovers from image building and debugging. Common examples include copied configuration files, package-manager credentials, temporary archives, shell history, and test secrets. The exact inspection commands depend on the operating system, so use its documented administrative tools rather than assuming a universal command.

Operate the agent and tunnel safely over time

Long-lived agents should be managed like other remote services. Assign an owner, document why the environment exists, define how it is patched, and set a review date. A forgotten test environment can retain old dependencies and credentials long after its original task has ended.

Coordinate four separate lifecycles

The compute host, agent process, application endpoint, and tunnel are separate components. Stopping one does not necessarily clean up the others. For example, stopping a tunnel removes public reachability but does not stop the local agent. Stopping the agent may leave the host and Localtonet client active. Deleting a disposable host may not revoke an external API credential. Write the shutdown procedure so each component is addressed explicitly.

Rotate and revoke credentials

Rotate a credential when a task changes owners, the environment is cloned, a log may have captured a secret, or compromise is suspected. Revocation should be tested, not merely requested. After revoking a token, confirm that the old environment can no longer use it. Avoid sharing one credential across multiple agent hosts because shared identity makes attribution and selective revocation harder.

Patch the layers independently

The operating system, agent runtime, language dependencies, application framework, and Localtonet client have separate update cycles. Test updates in a disposable copy where practical. Rebuilding from a documented image can be more reliable than repeatedly modifying a machine whose state is no longer understood.

Minimize retained context and logs

Keep only logs necessary for security, operations, and debugging. Agent traces can contain prompts, source fragments, API responses, file paths, and command output. Apply retention and access controls appropriate to that content. Before exporting logs from the isolated host, inspect and redact them.

Use an incident cleanup checklist

If an agent executes an unexpected command, contacts an unexplained destination, reveals a secret, or modifies data outside its intended scope, stop the tunnel and application endpoint first to limit further remote interaction. Pause or isolate the host if evidence must be preserved. Revoke exposed credentials, inspect external systems for unauthorized actions, and rebuild the environment from a known state rather than assuming that deleting one suspicious file resolves the incident.

Troubleshooting common isolation and tunnel problems

The service works locally but not through the tunnel

Confirm that the Localtonet client is connected, that the intended tunnel is running, and that the tunnel targets the exact local IP address and port verified earlier. Remember that creating a tunnel is not the same as starting it. Also confirm that the application process is still running and that no local policy blocks the client device from reaching the target.

The public address opens the wrong application

Recheck the target port and inspect which process owns that listener using the operating system's documented tools. Development machines sometimes retain an old server on a familiar port. Stop the unintended listener, start the correct service, and repeat local verification before restarting remote testing.

The interface is reachable but users receive authorization errors

This usually indicates that connectivity is working and the application is rejecting the request. Verify the service's authentication configuration, credential scope, expected headers or session mechanism, and server logs. Do not remove authentication merely to make the tunnel test pass. Test with a newly issued low-privilege identity if the existing credential's status is uncertain.

The agent can read files it should not access

Stop the agent and review account permissions, mounted directories, shared volumes, inherited group membership, and copied files. Moving the workload to another directory is not enough if the runtime account can still traverse the rest of the filesystem. Correct the operating-system boundary, remove unnecessary mounts, and rebuild the environment if its state cannot be trusted.

The agent cannot install or run a required tool

Determine whether the task truly requires that capability. If it does, install the dependency during a controlled build phase instead of granting permanent administrative access to the running agent. When dynamic installation is essential, consider a disposable environment and limit available credentials and network destinations during package execution.

The tunnel disappears unexpectedly

A Localtonet tunnel is available only while the selected client or device remains connected and the tunnel is running. Check whether the isolated host stopped, slept, lost outbound connectivity, restarted the client, or terminated the tunnel. Platform-wide Token/Tunnel webhooks can be used to observe Connected and Disconnected state changes for selected Token Groups.

A raw TCP tunnel was created for a browser dashboard

A browser dashboard normally speaks HTTP and should use an HTTP tunnel. Replace the mismatched tunnel with the protocol appropriate to the application. Conversely, a service that requires its own raw TCP protocol should not be assumed to work correctly through HTTP routing.

The environment cannot be reproduced

Capture the base image, package versions, agent version, configuration schema, service startup procedure, local endpoint, and credential requirements without recording secret values. Move manual setup into reviewed deployment configuration. A reproducible build makes recovery, patch testing, and incident response more dependable.

Frequently asked questions