Why sandbox the entire AI agent workload

A coding task executes untrusted code

Ask an agent to update one dependency. It runs a package manager, which downloads other packages and may execute their install scripts. The build may load compiler plugins. Tests run project code. A dev server runs bundler plugins. A browser executes JavaScript returned by the application or by an external page.

The agent did not write most of that code, and neither did you. Even a correct agent can trigger a compromised dependency, a malicious repository hook, or a test fixture that was never safe to run on a developer machine.

The final Git diff does not show a script reading ~/.ssh, probing a local service, or sending an environment variable to the network. Reviewing the patch is necessary, but it cannot reconstruct everything that executed while producing the patch.

One sandboxed command is not enough

A command wrapper protects only commands that use it. An agent may invoke hundreds of tools during one task, and those tools start their own children:

agent
  ├─ package manager ─ install scripts
  ├─ compiler ─ linker ─ build helpers
  ├─ test runner ─ workers ─ project code
  ├─ dev server ─ bundler ─ plugins
  └─ browser ─ page JavaScript

If safety depends on the agent remembering to prefix every command, one missed prefix removes the protection. Confinement must follow the process tree automatically.

A separate Git worktree is also insufficient. It protects the parent checkout from ordinary edits, but it does not restrict reads from the home directory, access to credentials and Unix sockets, outbound connections, or use of a logged-in browser profile.

The sandbox should cover the complete workload

For a coding task, the boundary should contain:

• the disposable checkout;
• the agent and its shell;
• package managers, build tools, hooks, and tests;
• the dev server and its loopback network;
• a fresh browser profile when the task uses a browser.

These components do not need identical permissions. They need to remain inside one outer boundary. A package script should not escape because it was started by npm instead of the agent. A browser opening localhost should reach the disposable dev server, not services on the host. Downloads should land in the disposable filesystem, not the user's home directory.

In h5i, box shell and box run start the process tree inside a resolved policy. Their children inherit the boundary. A host-side browser open --in <box> places the browser in that same box.

Keep authority and approval outside

Not everything belongs inside. The policy must be resolved where the workload cannot rewrite it. Long-lived credentials should stay on the host and be injected only into approved requests. Execution evidence should be stored outside the box's writable paths.

The agent also should not approve its own output. The box may propose a patch, but a human reviews the diff and execution record before exporting or applying it to the parent repository.

This creates a useful asymmetry: the agent can work freely within the task boundary, while the path back to valuable state remains narrow and explicit.

Sandboxing limits damage; it does not prove correctness

A sandbox does not make generated code correct. An agent can write a vulnerability, run the wrong tests, or misunderstand the task without escaping any boundary. Human review and appropriate tests remain necessary.

The strength of the boundary also depends on the isolation mechanism. A worktree provides no process confinement. Host-kernel tiers still trust the host kernel. A microVM adds a separate guest kernel at greater cost. Network enforcement differs by tier, so the status of the actual run matters more than the word sandbox.

Finally, an allowed model request may contain source code. Local confinement cannot keep source private from a model endpoint that policy permits. Use a self-hosted model or disable model egress when source must not leave.

A practical test

Before trusting an agent sandbox, ask:

1. Do package scripts, compiler helpers, tests, and servers inherit the boundary?
2. Which home directory, credentials, sockets, and network destinations can they reach?
3. Does browser work use a fresh profile inside the same boundary?
4. Is execution recorded somewhere the workload cannot edit?
5. Can the agent modify the parent repository without human approval?

If the answers describe several unrelated boundaries, part of the workload is probably still running with ambient host authority.

Sources and further reading

• Sandbox the entire workflow, for the browser-to-patch workflow.
• Isolation tiers, for the enforcement and limits of each boundary.
• The first-box guide, for running one coding task in a box.

Questions that come up