Sandbox MCP

AI coding agents are powerful because they can execute code. That is also their biggest risk: experimentation can modify the developer's environment.

An agent that is genuinely useful has to be able to run npm install, apply a migration, try a build, or run code it has not read. Every one of those actions, performed on your machine, can install something you did not want, overwrite work in progress, burn your CPU, read your credentials, or leave behind an environment that no longer builds.

The usual answers are both bad. Deny the agent those tools and it can only guess. Allow them and you are trusting a probabilistic system with your laptop.

Sandbox MCP is the third answer: give the agent somewhere real to work that is not your machine.

"Experiment with this project, but don't touch my actual environment."

Without a sandbox

flowchart TD
    CC["Claude Code"] --> HOST["Your machine"]
    HOST --> A["npm install"]
    HOST --> B["scripts"]
    HOST --> C["migrations"]
    HOST --> D["file modifications"]
    HOST --> E["arbitrary execution"]

    classDef danger fill:#fdeceb,stroke:#d1453b,color:#7a1f18
    classDef actor fill:#eef2f7,stroke:#5b6b7f,color:#22303f
    class HOST,A,B,C,D,E danger
    class CC actor

With Sandbox MCP

flowchart TD
    CC["Claude Code"] --> MCP["FastMCP"]
    MCP --> POL["Experiment policy"]
    POL --> SBX["Docker sandbox"]
    SBX --> WORK["execute · modify · test<br/>build · experiment"]
    WORK --> RES["Results"]
    RES --> CC

    classDef safe fill:#e7f4ea,stroke:#2f7d4f,color:#14432a
    classDef actor fill:#eef2f7,stroke:#5b6b7f,color:#22303f
    class SBX,WORK safe
    class CC,MCP,POL,RES actor

What makes this different from a Docker MCP server

Existing Docker MCP implementations expose Docker operations to AI agents. Sandbox MCP exposes an experimentation abstraction.

That is not a wording preference; it changes what the agent can do.

The agent never receives Docker API access. It states an intent; the server decides how that intent is realised.

flowchart TB
    CC["Claude Code"] -- "MCP tool call" --> SERVER

    subgraph SERVER["Sandbox MCP · the only component holding the socket"]
        direction LR
        POL["Policy / Security<br/><i>validates · clamps · refuses</i>"]
        EXP["Experiment Manager<br/><i>lifecycle · state machine</i>"]
        JOB["Job Manager<br/><i>async · timeouts · cancellation</i>"]
        COL["Result Collector<br/><i>diffs · artifacts · reports</i>"]
        POL --> EXP --> JOB --> COL
    end

    SERVER --> API["Docker Engine API<br/><i>/var/run/docker.sock — SDK only, no docker CLI</i>"]
    API --> SBX["Disposable sandbox<br/><i>no socket · no host filesystem · no network</i>"]
    SBX --> OUT["Structured result<br/><i>back to Claude Code</i>"]

    classDef actor fill:#eef2f7,stroke:#5b6b7f,color:#22303f
    classDef infra fill:#eaf1fb,stroke:#3a6ea8,color:#173352
    classDef safe fill:#e7f4ea,stroke:#2f7d4f,color:#14432a
    class CC,POL,EXP,JOB,COL,OUT actor
    class API infra
    class SBX safe
    style SERVER fill:#fbfcfd,stroke:#9aa7b4,color:#22303f

Docker is the isolation mechanism. MCP is the agent interface. Sandbox MCP is the experimentation layer.

There is deliberately no orchestrator here. The agent already is one: Claude Code plans, reads output, forms a hypothesis and retries better than any loop this server could ship. Putting a second, dumber loop underneath it would only compete with the caller. This project's job is the surface the agent drives — and making that surface one it cannot hurt you with.

The central abstraction: an experiment

Experiment:      exp_2859b8eb8656
Project:         payments-service
Base image:      node:22-slim
Network:         disabled
CPU:             2 cores
Memory:          1GB
Timeout:         300s
Status:          READY

Commands:        1. npm install --no-audit --no-fund   (exit 1, EBADENGINE)
                 2. npm install --no-audit --no-fund   (exit 0)
                 3. npm test                           (37 passed, 3 failed)
                 4. npm test                           (40 passed, 0 failed)

Changes:         3 files modified, +9 -4

Experiments move through an explicit, validated state machine. An illegal transition is an error, not a silently corrupted record — which matters, because DESTROYED is what tells the server a container no longer exists.

stateDiagram-v2
    direction TB
    [*] --> CREATING
    CREATING --> READY: sandbox provisioned
    READY --> RUNNING: command submitted
    RUNNING --> READY: exit 0

    state "terminal, but the sandbox is still alive" as OUTCOME {
        direction LR
        COMPLETED
        FAILED
        TIMEOUT
        CANCELLED
    }

    CREATING --> FAILED: could not start
    RUNNING --> OUTCOME
    OUTCOME --> RUNNING: more work
    OUTCOME --> DESTROYED: destroy_experiment
    READY --> DESTROYED: destroy_experiment
    DESTROYED --> [*]

Security model

The Docker socket is a highly privileged interface — access to it is effectively root on the host. It is held by the server and by nothing else. The agent talks to the server; the server talks to Docker.

Filesystem

The project is copied, not mounted:

flowchart LR
    HOST["HOST PROJECT<br/><i>read once, never written</i>"]
    SNAP["SANDBOX COPY<br/><i>also the baseline every diff uses</i>"]
    CON["DOCKER CONTAINER"]

    HOST -- "snapshot: filtered, read-only pass" --> SNAP
    SNAP -- "put_archive" --> CON
    CON -. "no path back" .-x HOST

    classDef host fill:#fdeceb,stroke:#d1453b,color:#7a1f18
    classDef safe fill:#e7f4ea,stroke:#2f7d4f,color:#14432a
    class HOST host
    class SNAP,CON safe

• Default strategy is COPY_TO_SANDBOX. READ_ONLY_BIND_MOUNT exists for large repositories you only need to read. Writable host bind mounts are not implemented — there is no configuration that produces one.

• .env files, *.pem, *.key, id_rsa*, .netrc, .ssh/, .aws/, .gnupg/, .kube/ and similar are never copied, regardless of configuration. Build output (node_modules, dist, target, …) is skipped by default and that list is configurable.

• Project paths are resolved before they are checked, so a symlink cannot launder a denied location. The home directory and filesystem root are refused outright.

• Paths inside the sandbox are confined to the workspace: ../../etc/passwd and /etc/shadow are rejected by every tool that takes a path.

One deliberate exception worth knowing: .npmrc is copied, because the real behaviour of npm install often depends on it. If yours holds an _authToken, add it to SANDBOX_MCP_SNAPSHOT_EXCLUDES.

Network

Disabled by default. network_mode is an explicit decision at creation time:

restricted prevents lateral movement between sandboxes. It does not firewall egress; per-experiment network allowlists are listed under future extensions.

Environment variables

The host environment is never inherited. Variables cross the boundary only when named: "CI" forwards the host's value, "NODE_ENV=test" injects a literal.

Credential-shaped names (*_TOKEN, *_SECRET, *API_KEY*, AWS_*, DATABASE_URL, …) are refused even when explicitly allowlisted, because an agent asking for AWS_SECRET_ACCESS_KEY inside a throwaway container is never right. Set SANDBOX_MCP_STRICT_ENV_DENYLIST=false if you disagree.

Values are never written to the database or the logs — only names.

Container privileges

• privileged=False, always. There is no setting that changes it.

• cap_drop: ALL, then a small set added back: CHOWN, DAC_OVERRIDE, FOWNER, FSETID, SETUID, SETGID, KILL. That is what package managers actually need (they chown caches and drop privileges for lifecycle scripts). It excludes NET_RAW, MKNOD, SYS_ADMIN, SYS_CHROOT, SETPCAP and SETFCAP — the ones that matter for escape.

• no-new-privileges:true.

• The Docker socket is never mounted into a sandbox. There is no code path that does it, and an integration test asserts its absence.

• SANDBOX_MCP_SANDBOX_USER runs containers as a non-root user where the toolchain tolerates it.

Resource limits

Every sandbox is capped, and a request may only ask for less than the configured ceiling. Asking for more is clamped, and the clamp is returned to the agent as a warning rather than failing silently.

Installation

Requires Python 3.12+ and a running Docker engine (Docker Desktop, OrbStack, Colima or Rancher Desktop).

git clone https://github.com/Dhananjay-JSR/sandbox-mcp.git
cd sandbox-mcp
uv sync                     # exact versions from uv.lock

Confirm the server can reach Docker before wiring it to anything:

uv run sandbox-mcp --check

{
  "docker_host": "unix:///var/run/docker.sock",
  "state_dir": "/Users/you/.sandbox-mcp",
  "defaults": { "base_image": "debian:bookworm-slim", "network_mode": "none", ... },
  "docker": { "server_version": "29.4.0", "api_version": "1.54" },
  "ok": true
}

ok: false with DOCKER_UNAVAILABLE means the daemon is not running or the socket is somewhere unusual. The server probes /var/run/docker.sock, ~/.docker/run/docker.sock, ~/.orbstack/run/docker.sock, ~/.colima/default/docker.sock and ~/.rd/docker.sock in that order — the Docker CLI's context is not consulted, so set DOCKER_HOST explicitly if yours is elsewhere.

Optional extras:

uv sync --extra dev     # pytest, ruff, mypy

Connecting Claude Code

Local (stdio) — recommended

claude mcp add sandbox -- uv --directory /absolute/path/to/sandbox-mcp run sandbox-mcp

Or, if you installed it into an environment already on your PATH:

claude mcp add sandbox -- sandbox-mcp

Then, inside Claude Code:

/mcp                       # should list "sandbox" as connected

Equivalent .mcp.json, if you prefer to commit the configuration:

{
  "mcpServers": {
    "sandbox": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/sandbox-mcp", "run", "sandbox-mcp"],
      "env": {
        "SANDBOX_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Remote (Streamable HTTP)

uv run sandbox-mcp --transport http --host 127.0.0.1 --port 8000
claude mcp add --transport http sandbox http://127.0.0.1:8000/mcp

Or run the server itself in a container:

docker compose up -d
claude mcp add --transport http sandbox http://127.0.0.1:8000/mcp

The compose file mounts the Docker socket into the server — read the warning at the top of it first, and do not expose port 8000 beyond localhost without authentication in front of it.

flowchart TD
    CC["Claude Code"] --> SRV["Sandbox MCP<br/><i>holds the socket</i>"]
    SRV --> ENG["Docker Desktop / OrbStack"]
    ENG --> SBX["Sandbox<br/><i>no socket · no host filesystem · no network</i>"]

    classDef actor fill:#eef2f7,stroke:#5b6b7f,color:#22303f
    classDef infra fill:#eaf1fb,stroke:#3a6ea8,color:#173352
    classDef safe fill:#e7f4ea,stroke:#2f7d4f,color:#14432a
    class CC,SRV actor
    class ENG infra
    class SBX safe

Tools

Notably absent: docker_run, docker_exec, docker_ps, docker_build, docker_pull. A test asserts that no tool name begins with docker_.

Resources

sandbox://experiments                              all experiments
sandbox://experiments/{experiment_id}              metadata + state history
sandbox://experiments/{experiment_id}/logs         every command, with output
sandbox://experiments/{experiment_id}/diff         unified diff
sandbox://experiments/{experiment_id}/artifacts    collected files

The primary demo: Node 20 → Node 22

examples/node-upgrade/ is a real, dependency-free Node library pinned to Node 20. It fails on Node 22 for two independent and entirely realistic reasons:

1. package.json declares engines.node: ">=18 <21" and .npmrc sets engine-strict=true, so npm install fails with EBADENGINE before a single test runs.

2. src/crypto.js calls crypto.createCipher, deprecated since Node 10 and removed in Node 22.0.0.

Ask Claude Code:

Determine whether examples/node-upgrade can be upgraded from Node 20 to Node 22. You may install dependencies, modify files, run tests and experiment freely, but do not modify my actual working tree.

What happens — every figure below is from an actual run, and the whole thing works with the network disabled:

sequenceDiagram
    autonumber
    participant CC as Claude Code
    participant S as Sandbox MCP
    participant D as Disposable sandbox

    CC->>S: create_experiment(node:22-slim, network none)
    S->>D: snapshot 13 files, start container
    S-->>CC: exp_2859b8eb8656 · READY

    CC->>S: execute_experiment("npm install")
    S-->>CC: exit 1 · EBADENGINE
    CC->>S: read_sandbox_file("package.json")
    S-->>CC: engines.node ">=18 <21"
    CC->>S: write_sandbox_file("package.json", ">=18")
    CC->>S: execute_experiment("npm install")
    S-->>CC: exit 0

    CC->>S: run_tests()
    S-->>CC: 37 passed · 3 failed<br/>seal produces hex output<br/>seal and open round-trip<br/>seal round-trips unicode
    CC->>S: read_sandbox_file("src/crypto.js")
    S-->>CC: crypto.createCipher(...)
    CC->>S: write_sandbox_file("src/crypto.js", createCipheriv + scrypt key + IV)
    CC->>S: run_tests()
    S-->>CC: 40 passed · 0 failed

    CC->>S: inspect_changes()
    S-->>CC: 3 modified · +9 -4
    CC->>S: collect_artifacts(["src/crypto.js"])
    S-->>CC: kept for the developer
    CC->>S: destroy_experiment()
    S->>D: remove container and snapshot
    S-->>CC: report · host working tree UNCHANGED

Experiment:         Node 20 → Node 22
Result:             COMPATIBLE (with 2 source changes)
Tests:              40 passed, 0 failed
Changes:            3 files modified (+9 -4)
Host working tree:  UNCHANGED
Sandbox:            DESTROYED

That last pair of lines is the product. This exact sequence runs as a test:

uv run pytest tests/integration/test_node_upgrade_demo.py -m integration

Other things this makes possible

• Dependency upgrade — "try upgrading React to the latest compatible version; don't modify my working tree." Needs network_mode="restricted" to reach the registry.

• Database migration — create an experiment on postgres:16, run the migration, report whether it applied, destroy it.

• Build debugging — "work out why this build fails; experiment freely."

• Multi-approach debugging — examples/failing-project/ is a Python project whose money arithmetic is done in floats; 3 of its 14 tests fail. Three fixes are plausible (round(), Decimal, truncation) and they are not equivalent. Run each in its own experiment, then call compare_experiments, which ranks them on failures, exit code, change size and duration, and recommends one.

Why there is no orchestration layer

An earlier cut of this server shipped a LangGraph loop — plan, test, diagnose, fix, retest — behind a run_autonomous_experiment tool. It was removed, on purpose.

The caller is already an agent. Claude Code reads a failing test, forms a hypothesis, edits a file and retries; it does that better than a graph of hardcoded repair strategies ever will, because it has judgement and the strategies had a lookup table. Shipping a second, weaker loop underneath a strong one does not add a capability — it competes with the caller for the same decision, and it is the one more likely to be wrong.

What is left is the part the agent genuinely cannot do for itself: the isolation boundary, the policy that enforces it, the state machine, the baseline diff, and the audit trail. Those are the product.

Concretely, the loop lives in the transcript instead of inside the server:

flowchart LR
    DEC["Decide the next step<br/><i>Claude Code — the loop lives here</i>"]
    ACT["Call a tool"]
    SRV["Sandbox MCP<br/><i>enforces · refuses · records</i>"]
    OBS["Read the full output"]

    DEC --> ACT --> SRV --> OBS --> DEC

    classDef actor fill:#eef2f7,stroke:#5b6b7f,color:#22303f
    classDef safe fill:#e7f4ea,stroke:#2f7d4f,color:#14432a
    class DEC,ACT,OBS actor
    class SRV safe

That is the primary demo, and it is what the integration suite runs.

Observability

Every operation emits a structured JSON event to stderr (stdout carries the MCP protocol under stdio transport):

{"event": "command_completed", "experiment_id": "exp_2859b8eb8656",
 "job_id": "job_4f1c8a2b90de", "operation": "job.run", "status": "COMPLETED",
 "exit_code": 0, "duration_ms": 1432, "timestamp": "2026-09-07T10:29:41Z"}

Credential-shaped keys are scrubbed at the processor level, so no individual call site can leak by forgetting.

Everything needed to answer "what exactly did the agent do?" is persisted in SQLite (~/.sandbox-mcp/sandbox.db): experiments, jobs with their commands, exit codes and captured output, state transitions with timestamps and reasons, artifacts with checksums, the pre-container baseline, and the change statistics — which are written before teardown, so a destroyed experiment is still comparable against a live one.

The database stores no secrets: environment variable names, never values.

Project layout

src/sandbox_mcp/
├── server.py            MCP tools and resources — the agent-facing surface
├── app.py               composition root; the only place the graph is wired
├── config.py            every tunable, in one auditable place
├── models.py            domain models (experiments, jobs, changes, reports)
├── errors.py            structured errors; no traceback ever reaches a client
├── logging.py           structured logging to stderr, with redaction
├── sandbox/
│   ├── interface.py     SandboxBackend — the seam other runtimes target
│   └── docker.py        Docker Engine API via the SDK; all hardening lives here
├── experiments/
│   ├── manager.py       the domain core
│   ├── state.py         the validated state machine
│   ├── repository.py    ExperimentRepository + the SQLite implementation
│   ├── changes.py       diffing the sandbox against its baseline
│   └── testing.py       test-runner detection and output parsing
├── execution/
│   ├── manager.py       job lifecycle: timeouts, cancellation, persistence
│   ├── jobs.py          live task registry and concurrency limits
│   └── executor.py      JobExecutor interface + the sandbox implementation
├── artifacts/manager.py pulling files out before teardown
└── security/
    ├── policy.py        validates and clamps every request
    ├── filesystem.py    path confinement and snapshotting
    └── resources.py     limit parsing

SandboxBackend, ExperimentRepository and JobExecutor are abstract. Docker implements the first; the MCP tool surface does not know it exists. Supporting Firecracker, Kubernetes Jobs or remote workers means one new implementation and no change to the agent-facing API — the in-memory FakeSandboxBackend the unit tests run against is the proof that the seam is real.

Three deviations from a literal reading of the brief, all deliberate: experiments/changes.py and experiments/testing.py exist as focused modules rather than being folded into manager.py; commands/results are columns on the jobs table rather than separate tables, since a job is a command and its result; and there is no orchestration/ package, for the reason given above.

Development

uv sync --extra dev

uv run pytest -m "not integration"     # 225 unit tests, no Docker needed
uv run pytest -m integration           # 23 tests against a live daemon
uv run pytest                          # everything

uv run ruff check . && uv run ruff format --check .
uv run mypy

The unit suite runs against FakeSandboxBackend and needs no daemon. The integration suite is the one that proves the product claim: the nine-step isolation checklist, the host tree unchanged byte-for-byte, the network genuinely off, secrets genuinely absent, the memory cap actually biting, timeouts killing the process, cancellation killing the process, hardening flags present on the real container, orphan containers swept at startup, and the full Node 20 → 22 demo.

MVP boundaries

Not built, on purpose: a web dashboard, authentication, cloud infrastructure, Kubernetes support, distributed scheduling, billing, multi-tenant production infrastructure. This is a polished local-first MVP.

Known limits, stated plainly:

• Killing a timed-out command signals the command's own process. Descendants it spawned may survive until the sandbox is destroyed; pids_limit bounds the damage in the meantime.

• restricted networking isolates sandboxes from each other but does not filter egress.

• Change detection covers regular files. Symlinks are copied but not tracked in diffs.

• Per-sandbox disk quotas need a storage driver that supports them (overlay2 on XFS with pquota); /tmp is capped via tmpfs, the workspace is not.

Future extensions

1. Remote sandbox execution

2. Firecracker isolation

3. Kubernetes sandbox workers

4. Persistent base-image cache

5. Snapshot / restore

6. Parallel experiments

7. Experiment replay

8. Resource usage analytics

9. Network allowlists

10. Human approval before applying changes

11. Agent experiment benchmarking

Licence

MIT.