How to Sandbox an AI Coding Agent

Quick answer
A sandbox limits what a process can touch: which files it can read or write, which network destinations it can reach, and which credentials it holds.
The practical tools are an isolated workspace (a container or a disposable VM), a non-privileged user, a mounted credential store with only what the task needs, and network egress rules.
The goal is not to stop the agent from doing its job but to bound the damage when it misunderstands one — a deleted directory rather than a deleted account.
Test the sandbox by trying to do something it should forbid, and fix what still succeeds, rather than assuming the configuration took effect.
Sandboxing and approvals are complementary: the sandbox limits scope, confirmation prompts limit irreversible actions.

What does sandboxing an AI coding agent mean?

It means running the agent inside a boundary the agent cannot widen. Four dimensions matter. Filesystem: what it can read and write, and whether writes outside the project are possible. Identity: which user it runs as, since a process running as your user inherits everything that user can do. Credentials: which tokens and keys are visible in its environment, because an agent that can read your shell environment can use any key you exported there. Network: where it can send data, because an agent with unrestricted outbound access can exfiltrate whatever it has read.

The threat model is not a malicious model; it is a capable one having a bad day. An agent that misreads an instruction, follows a plausible-looking shell command from a document it was asked to summarise, or interprets ‘clean up the build artifacts’ expansively can do damage quickly, with your privileges. The sandbox converts a class of catastrophic outcomes into recoverable ones.

Step 1 — isolate the workspace

Give the agent its own workspace rather than your machine’s filesystem. A development container with the project mounted is the usual baseline; a disposable virtual machine is the stronger option where the work justifies it. Mount only the repository or worktree the task concerns, and mount it where possible with restricted permissions. If the agent needs to write, give it a branch or a separate worktree so that the main checkout is not at risk.

The key point is that the mount defines the blast radius. A container with the whole home directory mounted is barely a sandbox; one with a single worktree mounted and nothing else visible is a meaningful one, and it costs nothing to set up once.

Step 2 — drop privileges and strip the ambient credentials

Run as a non-root user inside the sandbox, with no ability to elevate. The common failure is the container that runs as root by default, which the agent inherits — the same default that makes generated Dockerfiles dangerous. Then remove credentials from the environment: start the agent with a minimal environment instead of inheriting your shell, and hand it only the specific tokens the task needs. ‘Only what the task needs’ is the operative phrase; a deploy token is not needed to write a refactor.

Where the agent genuinely needs an external service, prefer a narrowly scoped credential minted for the task over your personal one. A short-lived token with a single repository and read-only scope limits what a mistaken command can reach. This is also the argument for using a dedicated machine account rather than your own identity, so revocation is available without changing your own access.

# A minimal sandbox for a coding agent, using a container and a task-scoped worktree.
# 1. A dedicated worktree, so the main checkout is not the working surface.
git worktree add ../agent-work -b agent/task-123

# 2. Run as a non-root user, with only the project mounted and a minimal env.
docker run --rm -it \
  --user 1000:1000 \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --mount type=bind,src="$PWD/../agent-work",dst=/work \
  --env AGENT_API_KEY \
  --network agent-net \
  -w /work \
  sandbox-image bash

# 3. Verify the boundary, do not assume it.
whoami                      # expect the unprivileged user
ls ~/.ssh 2>&1              # expect: no such file or directory
env | grep -i -E 'token|key|secret'   # expect: only the task-scoped values
curl -s -m 3 https://example.com >/dev/null && echo OPEN || echo BLOCKED

Step 3 — restrict network egress

Unrestricted outbound access is how anything the agent reads can leave. If the task does not need the network, turn it off; if it needs specific endpoints — a package registry, a model API — allow those and deny the rest. Container runtimes and cloud platforms can enforce this, and the configuration is easier while the environment is simple rather than after it has grown.

Egress rules also limit which malicious instructions can take effect. An agent that fetches a package on request and can reach only the registry cannot be redirected to fetch from somewhere unexpected. It is the same principle as allow-listing dependencies, applied to the agent’s own runtime.

Step 4 — restore what you need, deliberately

A sandbox that blocks the workflow will be turned off, so make the allowed path convenient. If the agent needs to run the test suite, give it a database and a network route to it in the sandbox rather than on your machine. If it needs to read documentation, mount the repository’s docs directory read-only. Each accommodation is a decision you make and can review, rather than a permission the agent accumulates by running as you.

Finally, combine the sandbox with human review of anything irreversible. Approve destructive commands, review diffs before they land, and keep the agent’s commits on a branch. The sandbox bounds damage; approvals prevent it. Neither is sufficient alone.

Where this bites vibecoders
Agents installed with default settings typically run as your user, in your shell environment, with your credentials and full network access — because that is the least friction and the README optimises for the first five minutes. Nothing in the setup mentions the boundary, so the boundary is effectively your whole account. Bringing the agent up inside a container with a minimal environment is thirty minutes of work that changes what a bad command can reach, and it does not slow the ordinary case down at all.

Where AI coding assistants get this wrong

Enabling an agent with auto-approval of shell commands while it runs as your user.
Passing the host environment, including all secrets, into the agent’s process.
Mounting the home directory into the sandbox because it is convenient.
Granting a personal credential instead of a task-scoped one.
Leaving network egress open when the task does not need the network.
Assuming the sandbox works without testing which operations are still permitted.

Checklist

Give the agent an isolated workspace or worktree.
Run as a non-privileged user that cannot elevate.
Pass a minimal environment with only task-scoped credentials.
Restrict network egress to the endpoints the task needs.
Mount documentation and data read-only where possible.
Attempt a forbidden action to verify the boundary holds.
Keep approvals on for anything irreversible.

FAQ

Is a container enough of a sandbox for a coding agent?

It is a large improvement and not a complete answer. A container isolates the filesystem and can drop capabilities and restrict network, which covers most of the risk. It does not protect against anything you mount into it or credentials you pass, and container escapes exist. For ordinary development work it is proportionate; for agents with production access, add scoped credentials and approvals.

Do I need to sandbox an agent that only edits files?

The restriction is enforced by the agent’s behaviour, not by the sandbox, so it is weaker than it sounds. An agent asked to complete a task may run the test suite, install dependencies, and invoke scripts — all of which execute code with your privileges. If it can run commands, it needs a boundary; if it truly only writes files, a separate worktree still limits the damage.

How do I stop the agent exfiltrating my source code?

Restrict network egress to the endpoints it genuinely needs, and do not give it credentials it does not need — with open network and a broad token, the source is not the only thing at risk. Note that a model API call is itself egress, so the rule is about narrowing destinations, not eliminating outbound traffic.

Does sandboxing slow down the agent?

Negligibly in compute terms, and somewhat in setup effort when the task needs a service inside the sandbox. The workflows that suffer are the ones that relied on broad ambient access. Once the container image includes the tools the project needs, day-to-day use is the same as before, with a boundary around it.