Skip to content
AI Engineer Guide.

concept · coding · intermediate · concept 18 of 30

Sandboxing

0 of 30 complete

Why it matters

A coding agent executes commands derived from model output and from repository content nobody reviewed. Both can be wrong and one can be hostile. The sandbox exists so that a bad command fails inside a boundary instead of on a developer laptop or a CI runner with credentials. Building it is a trade: too little isolation and a repository can reach production, too much and the agent cannot install a dependency or run the test suite.

Mental model

It is a fume hood where work happens inside and the exhaust is filtered. The metaphor breaks because the hood must also reach the package registry, and that duct is the one you were trying to filter, so egress becomes the design problem.

How it works

Layered boundary: commands, egress, credential, escapeInteractive
egress allowlist
Step 1/6 · workload
  1. neutral · sandbox · session
    untrusted workloadneutral
    Commands run · repo mounted rw
    call by name no key in the box
  2. trusted · host + proxy
    holds the credentialtrusted
    Credential proxy · adds auth
  3. Commands run · repo mounted rw· kernel or mount escape
    escape targettrusted
    Host filesystem
  4. untrusted · egress
    Commands run · repo mounted rw· install depsegress allowlist · open
    needed egressuntrusted
    Package registry · allowlisted
  5. Commands run · repo mounted rw· exfiltrateegress allowlist · open
    off-listuntrusted
    Any other host
trusted pathtainted pathcontrol openboundary holdspassespending approvaltrusted zoneuntrusted zoneneutral zone3 zones · 5 nodes · illustrative geometry

workload. Generated commands and test runs execute in one session. The repository is mounted read-write and everything else read-only, so the toolchain works without reaching the host.

Figure. The boundary drawn is the egress allowlist, with a credential proxy keeping the key outside the session. It refuses connections off the list and leaves the allowlisted registry open; it does not stop a kernel or mount escape, drawn with no gate, and it does not remove a long-lived credential placed inside. Shown with egress open; use Blocked to apply the allowlist.

What to notice. Residual risk: a container shares the host kernel, so the wall is thinner than the drawing suggests. Test with a canary file outside the sandbox and a canary host after every image or runtime change. The proxy's own upstream call is not drawn; its egress belongs to the proxy's allowlist. Shared long-lived sandboxes are omitted.

Text version

Three zones: TRUSTED · HOST + PROXY holds the credential proxy, which adds auth, and the host filesystem; NEUTRAL · SANDBOX · SESSION holds the commands that run with the repository mounted read-write; UNTRUSTED · EGRESS holds the allowlisted package registry and any other host. A solid path runs from the commands to the proxy, labelled call by name, no key in the box. A solid path runs to the registry, labelled install deps, and a dashed red path runs to any other host, labelled exfiltrate. Both egress edges carry the egress allowlist control: open, both leave; blocked, the registry edge gets a teal tick and the off-list edge is cut at a teal bar. A second dashed red path runs from the commands to the host filesystem, labelled kernel or mount escape, with no gate and no cut at any state.

  1. List what the task needs at runtime: language toolchains, a package cache, a database and any network endpoints.
  2. Choose the boundary from the threat model and the startup budget, comparing a container, a microVM and a user-space kernel.
  3. Mount the repository read-write and everything else read-only, with a scratch directory for temporary files.
  4. Deny network by default and allowlist package registries plus the APIs the tests genuinely call.
  5. Inject credentials at call time through a proxy rather than placing files in the sandbox.
  6. Destroy the environment after the run and rebuild from the image for the next task.

Trade-offs

ChoiceGood forCostFails when
ContainerFast startup, familiar toolingShared kernel, escape surfaceHost runs code from strangers
MicroVMStrong isolation, own kernelStartup and memory costTasks are short and numerous
User-space kernelFine-grained syscall policyCompatibility gaps with some toolchainsBuild needs unusual syscalls
Shared long-lived sandboxCheap, warm cachesCross-task state leakageMultiple tenants or secrets
Trade-off mapInteractive

Good for

Fast startup, familiar tooling

Cost

Shared kernel, escape surface

Fails when

Host runs code from strangers

  1. Host runs code from strangers
  2. Tasks are short and numerous
  3. Build needs unusual syscalls
  4. Multiple tenants or secrets

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Container is good for Fast startup, familiar tooling, costs Shared kernel, escape surface, and fails when Host runs code from strangers. MicroVM is good for Strong isolation, own kernel, costs Startup and memory cost, and fails when Tasks are short and numerous. User-space kernel is good for Fine-grained syscall policy, costs Compatibility gaps with some toolchains, and fails when Build needs unusual syscalls. Shared long-lived sandbox is good for Cheap, warm caches, costs Cross-task state leakage, and fails when Multiple tenants or secrets

Failure modes

  • Missing toolchain. The agent cannot run tests and reports success from reading code. Debug: run the project's build command in a fresh sandbox before the task starts.
  • Egress leak. A dependency post-install script posts environment variables to an external host. Debug: capture DNS and outbound connections and diff them against the allowlist.
  • State bleed. A file from the previous task changes this task's test result. Debug: diff the workspace against a clean checkout before the run.

In production

Monitor sandbox start latency, egress denials and image drift. Cap CPU, memory and wall-clock per task and kill the environment when a cap is breached.

Common misconceptions

People think: A container is a security boundary by default.

Actually: It is a process boundary over a shared kernel, so hostile code needs stronger isolation or a hardened runtime.

People think: Sandboxes are only about security.

Actually: They also make runs reproducible, which is why evaluation results depend on them.

Interview angle

Separate the isolation layers and choose a boundary from a stated threat model. A strong answer keeps the toolchain working inside the sandbox and covers egress and credential injection. Saying to use containers and stopping there ignores the shared kernel, the network policy and how dependencies get installed.

Sources