mcp-linux-sandbox

A disposable Debian Linux sandbox exposed as an MCP server, so a chat client (FlowDown, Claude Desktop, anything speaking Streamable HTTP) can run real shell commands — apt install, curl, ffmpeg, Python — and hand files back to you.

Each conversation gets its own container. Files under /workspace survive container recycling; installed packages and running processes do not.

MCP client ──Bearer──▶ nginx (TLS)
                         ├── /mcp/<random>/  ──▶ 127.0.0.1:8000  FastMCP
                         └── /dl/<signed>    ──▶ (same)  file links
                                                     │
                                                     ▼
                                    podman exec  mcpsb-<label>
                                                     │
                                        ┌────────────┴────────────┐
                                        ▼                         ▼
                              container writable layer     volume /workspace
                              (packages, /tmp — dies)      (files — survives)

Files

Related MCP server: railway-sandbox-mcp

Install

sudo dnf install -y podman catatonit        # catatonit is needed by podman --init
./env.sh                                    # creates mcp-sandbox.env, generates the signing key
vim mcp-sandbox.env                         # set MCP_PUBLIC_BASE
./install.sh                                # refuses to run while that is still the placeholder

Then wire up nginx — copy both blocks from nginx/mcp-sandbox.conf into your existing TLS server {}, replacing the path and token placeholders:

• generate the bearer token with openssl rand -hex 32

• on Fedora, sudo setsebool -P httpd_can_network_connect 1, or nginx gets 502

• sudo nginx -t && sudo systemctl reload nginx

Client configuration

Add this to the client's system prompt, or the per-conversation isolation does not happen:

When you call run_command, pass a sandbox label. At the start of a new conversation pick a NEW short label (for example amber-otter) and use that same label for every call in the conversation. Never reuse a label from an earlier conversation, and do not change it mid-conversation.

Verify with, from the install directory (install.sh copies selftest.py there):

cd ~/mcp-linux-sandbox                      # or wherever SANDBOX_HOME points
./venv/bin/python selftest.py --url https://your.host:8443/mcp/<path>/ --token <token>
./venv/bin/python selftest.py --url http://127.0.0.1:8000/mcp    # bypasses nginx

Sandbox labels

Tools take a sandbox label, and label → container → volume is one to one: a label with no container yet gets a fresh, empty one. Labels are normalised, so Amber Otter and amber-otter reach the same sandbox.

The label has to come from the model because the client sends one MCP session id for the whole app rather than one per conversation, and no per-conversation field exists in the request. It is a convention rather than a guarantee — a model that reuses a label reaches the old container — but every result echoes [sandbox <key>] [new], so a collision is visible rather than silent.

Settings

Volumes are never deleted by the server. gc-volumes.sh handles that on a timer and is dry-run by default.

Security

This endpoint executes arbitrary commands. Treat it accordingly.

• Keep the client's tool-confirmation prompt enabled. It is the only human gate on what actually runs.

• Anything that can reach /mcp/ can run code; anything that can reach /dl/ can read the sandbox volume. Keep the bearer token and MCP_SIGN_KEY out of URLs, screenshots, .fdmcp-style exports, cloud drives and git.

• present_file serves regular files under /workspace and follows no symlink in any path component, so a link created inside the sandbox cannot reach host files.

• Containers are rootless (podman, no sudo) and can reach the LAN by default. If that matters, drop the network (--network=none) or move the container onto an --internal network behind a proxy — but installing packages needs network, so pick one.

• Isolation is namespace + seccomp + cgroups, not a VM. It is the right level for "stop the model from trashing my host"; it is not gVisor/Kata.

Limitations

• The sandbox boundary is the model's own label discipline, as described above.

• Concurrent conversations share the container budget. With SANDBOX_MAX=2, a third conversation evicts the LRU container — packages go, files stay.

• Restarting the service invalidates the client's MCP session; the client has to re-verify.

• Image attachments depend on the client. FlowDown attaches MCP image content; other clients may not.

• gc-volumes.sh's age heuristic (newest mtime in the volume) has not been validated on btrfs. Keep DRY_RUN=1 until you have watched it for a while.

Verified behaviour

Checked end-to-end against a live deployment (Raspberry Pi, Fedora 44 aarch64, rootless podman, cgroup v2, behind nginx):

Not yet exercised: the over-age branch of gc-volumes.sh.