sandbox-mcp

Let an LLM fetch the web, write scripts, and run them — without letting it do those things anywhere near your agent's process.

Policy-driven MCP servers for capabilities that are unsafe to run in-process. What is allowed — domains, languages, resource ceilings, what needs approval — is a policy file, not code.

The one idea

Two servers, split on the axis that matters:

Neither can both execute arbitrary code and reach the network.

A prompt injection in fetched content has no way to run. Code that runs has no way to phone home. That separation is the whole point, and it is why these are not one convenient server.

Related MCP server: mcp-safeguard

What makes this different

Most sandboxes describe their guarantees. This one attacks itself in CI — 40 tests run against real containers and attempt fork bombs, infinite loops, DNS exfiltration, privilege escalation, audit forgery, path traversal, and SSRF via redirect. Six real bugs were found that way, none of which were visible in review:

• --network=none makes the MCP port unreachable — and the obvious replacement still resolves DNS, which exfiltrates data one subdomain label at a time.

• The wall-clock timeout could not kill anything: signalling across uids needs CAP_KILL.

• Fork-bomb survivors outlived their call and degraded the sandbox until restart.

• RLIMIT_NPROC counts per-UID system-wide, not per process tree.

• PATH was inherited wholesale from the host environment.

• The audit trail silently wrote nowhere on a uid-mismatched bind mount.

SECURITY.md states the threat model and the non-goals. The non-goals matter as much: a sandbox that oversells itself is worse than one that tells you where it stops.

Status: 0.6.0, early development but in daily use. Both servers, the approval broker, and the adversarial suite are complete, and an independent security audit has been run and acted on (AUDIT-fable5-2026-07-25.md). See CHANGELOG.md and ROADMAP.md.

Quick start: sandbox-exec

podman build -f Dockerfile.exec -t sandbox-exec:dev .
cp policies/exec.example.yaml ./exec.yaml
mkdir -p -m 700 audit approvals

# An *internal* network, not --network=none: the server still has to be
# reachable on its MCP port. See "Networking" below -- this combination is
# what actually blocks egress, and it is verified by the test suite.
podman network create --internal sandbox-net

podman run --rm \
  --network=sandbox-net --dns=none \
  --read-only \
  --cap-drop=ALL --cap-add=SETUID --cap-add=SETGID --cap-add=CHOWN --cap-add=KILL \
  --security-opt no-new-privileges \
  --memory=512m --cpus=2 --pids-limit=256 \
  --mount type=tmpfs,destination=/workspace,tmpfs-size=64m \
  --mount type=tmpfs,destination=/tmp,tmpfs-size=16m \
  -v ./exec.yaml:/policy/exec.yaml:ro \
  -v ./audit:/audit \
  -v ./approvals:/approvals \
  -p 127.0.0.1:8801:8801 \
  sandbox-exec:dev

Register it with any MCP client by URL — for example:

hermes mcp add sandbox-exec --url http://127.0.0.1:8801/mcp

Networking

--network=none is the obvious choice and it does not work: it leaves the MCP port unreachable, so nothing can call the server. What is needed is a network the host can reach inward on while the container cannot reach outward:

Everything else is dropped: no DAC_OVERRIDE (root cannot bypass file permissions), no NET_*, no SYS_*.

Verified by tests/security/test_container.py: TCP egress, DNS resolution, and host-network access are each attempted and must fail, and a fork bomb must not leave the sandbox degraded.

Quick start: sandbox-fetch

The fetcher is the inverse: it may reach the network, so it never executes anything, needs no capabilities at all, and runs unprivileged from PID 1.

podman build -f Dockerfile.fetch -t sandbox-fetch:dev .
cp policies/fetch.example.yaml ./fetch.yaml
mkdir -p -m 700 audit

podman run --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt no-new-privileges \
  --userns=keep-id:uid=10003,gid=10003 \
  --memory=256m --cpus=1 --pids-limit=64 \
  -e OLLAMA_BASE_URL=http://127.0.0.1:11434 \
  -v ./fetch.yaml:/policy/fetch.yaml:ro \
  -v ./audit:/audit \
  -p 127.0.0.1:8802:8802 \
  sandbox-fetch:dev

--userns=keep-id is not cosmetic. Without it the bind-mounted audit directory is owned by the host user — which maps to uid 0 inside a rootless container — while the server runs as uid 10003, so every audit write fails. Records still reach stderr, but the file you would actually go read stays empty. The server warns about this at startup.

Tools

sandbox-exec — four tools:

Nouns with an action argument, not seven verbs: list_files used to be matched against the ordinary word "List" in an unrelated question, and the agent answered about the sandbox instead. Schemas also cost ~1.8 KB each in every prompt.

Command output is capped at limits.max_output_bytes (default 8000) and lands directly in the caller's context, so it is the most expensive thing this server produces. Write bulk results to the workspace and read back only what you need. Truncation keeps the head and the tail, so a traceback at the end of a noisy run survives.

sandbox-fetch — fetch_url(url). Returns extracted text, or a refusal naming the rule that fired.

What the fetcher checks, in order

Every one of these re-runs on each redirect hop, not just on the URL you passed. A hop is a request the process actually makes, so a redirect landing on an internal address is a live SSRF no matter where the chain ends.

The User-Agent is policy-only and deliberately not caller-settable. A header the model controls, sent to an allowlisted host, is an exfiltration channel — the exact property the two-container split exists to prevent.

API routes: ask for the API, not the page

Scraped HTML carries menus, infoboxes, and edit links around the text you wanted. That wastes the caller's character budget, and markup remnants read like injected instructions to a reviewer. Where a site publishes JSON for the same content, policy can say so:

api_routes:
  - match: "*.wikipedia.org"
    when_path: "^/wiki/(?P<title>.+)$"
    url: "https://{host}/api/rest_v1/page/summary/{title}"
    extract: ["description", "extract"]   # dotted paths, joined in order
    on_miss: fallback                     # or `error` to require the API

Measured on the same article: 559 characters of clean prose instead of about 8000 of page furniture.

There is no per-site code — a route is four lines of policy, so adding a site is a reviewable diff rather than a release. And a route is a rewrite, never a bypass: the rewritten URL goes through the full allowlist and SSRF check before anything is requested, substituted values are percent-encoded so a title cannot climb out of its path segment, and a template naming a placeholder that does not exist fails at startup rather than on first use.

Policy

See policies/exec.example.yaml and policies/fetch.example.yaml. Mount it read-only so the container cannot rewrite its own rules. A missing or malformed policy is a startup failure — there is no permissive fallback.

Environment variables carry only operational settings (POLICY_PATH, AUDIT_PATH, HOST, PORT); capability decisions live in the policy file, where they are structured, reviewable, and not visible in podman inspect.

Approval

The executor has no network, so approval cannot be a webhook. It travels over a bind-mounted directory:

/approvals/pending/<id>.json     server writes, then blocks
/approvals/decisions/<id>.json   anything can write the verdict

Timeout means deny. No transport is baked in — bridging that queue to Telegram, Slack, a TUI, or a web UI is a separate component, which is what keeps this project free of any of them. Approving by hand is just:

echo '{"approved":true,"reason":"looks fine"}' > approvals/decisions/<id>.json

Providers: deny_all (default), file_queue, command, webhook.

A working broker for the other end ships in contrib/approval-broker/ — one stdlib-only file, with console and Telegram adapters. It lives outside src/ on purpose, so no chat transport can end up in the sandbox image:

python3 contrib/approval-broker/approval_broker.py --queue ./approvals

Skills

The workspace is a tmpfs and dies with the container, so nothing an agent builds survives. A skills directory is durable storage for reusable scripts, off by default:

skills:
  enabled: true
  path: /skills
  writable: false     # see below
  max_mb: 16

Adds the skill tool: list and read always, save only when writable.

writable defaults to false deliberately. A persistent, writable store of executable code is somewhere a prompt injection can leave something behind for a later, unrelated call to pick up — a different threat from everything else here, where every workspace is ephemeral. When it is false the save_skill tool is not registered at all, rather than registered and failing; an absent tool cannot be talked into trying. Skills are never executed implicitly: they are inert files the caller may choose to run through the normal gated tools.

Mount it read-only unless you want the agent curating its own skills, and watch skill_saved in the audit log if you do:

-v ./skills:/skills:ro

Security

Read SECURITY.md — it documents the threat model and the non-goals, which matter just as much. The short version: the container is the boundary; everything else narrows what happens inside it.

Guarantees are covered by an adversarial test suite rather than asserted:

make check          # ruff (incl. bandit rules), mypy --strict, bandit, pip-audit
make test-security  # fork bombs, infinite loops, network access, privilege escalation

Development

make install         # venv + dev extras
make check           # lint, types, static analysis, dep CVEs, non-container tests
make build           # both images
make test-security   # the adversarial suite against real containers
make scan-image      # trivy, both images

make check must pass before anything is done. See CONTRIBUTING.md — the one rule is that a change widening what the sandbox permits arrives with an adversarial test that fails without it.

Documentation

License

MIT — see LICENSE.