<!-- SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com> SPDX-License-Identifier: Apache-2.0 -->
mcp-sandbox
MCP server for isolated scientific script execution. Run R, Python, GMT, GRASS GIS, LaTeX, Octave, Julia, and more in disposable containers — fully stateless, no host filesystem access.
Tools
| Tool | Description | | --------------- | ------------------------------------------------- | | run_script | Execute a script in an isolated sandbox container | | list_runtimes | List available scientific runtimes |
Supported Runtimes
| Runtime | Tools | | --------- | ----------------------------------------------------------------------- | | r | R + ggplot2, dplyr, tidyr, jsonlite | | python | Python 3 + numpy, scipy, pandas, matplotlib, sympy, scikit-learn, geopandas, pyproj, rasterio, obspy | | gmt | Generic Mapping Tools | | grass | GRASS GIS — headless; each run gets a throwaway location | | latex | pdflatex (texlive) | | octave | GNU Octave | | julia | Julia | | gnuplot | Gnuplot | | bash | Bash scripts |
Design
- Each run spawns a fresh container — fully stateless, no reuse
- Container deleted after execution (
--rm) - Network access enabled
- Memory limit: 2GB, CPU limit: 2 cores
- Input files injected at
/sandbox/input/(base64) - Output files collected from
/sandbox/output/, returned by reference: a
capability URL plus metadata (name, bytes, SHA-256, MIME, expiry). Small text outputs (< 4 KB) are still inlined. See "Output handling" below.
Install
The sandbox runs containers rootless, as a dedicated sandbox user. The image and the running service must live in that user's podman store. This is the single most important thing to get right — see Troubleshooting.
1. Create the service user
useradd -r -m -d /var/lib/mcp-sandbox -s /bin/bash sandbox
echo "sandbox:100000:65536" >> /etc/subuid
echo "sandbox:100000:65536" >> /etc/subgid
# rootless podman needs a runtime dir (/run/user/<uid>) present at boot:
loginctl enable-linger sandbox2. Build the image — as the sandbox user
Build into the sandbox user's rootless store. Not your login user's, not root's — the server only ever reads sandbox's store:
sudo -u sandbox -H podman build -t mcp-sandbox:latest -f Containerfile .Already built the image elsewhere? Don't rebuild — transfer it across the store boundary:
podman save mcp-sandbox:latest | sudo -u sandbox -H podman load3. Install the server
python3 -m venv venv
venv/bin/pip install -e .Running as a service
Run the server as sandbox so it reads that user's image store. Minimal unit (adjust the checkout path and entrypoint to your install):
# /etc/systemd/system/mcp-sandbox.service
[Unit]
Description=mcp-sandbox MCP server
After=network.target
[Service]
User=sandbox
ExecStart=/var/lib/mcp-sandbox/mcp-sandbox/venv/bin/mcp-sandbox
Restart=on-failure
[Install]
WantedBy=multi-user.targetAdding dependencies
The image is the single source of truth for what a runtime can do. Because every run is a fresh --rm container, a runtime pip install inside a sandbox does not persist — it re-downloads and rebuilds on every invocation, and on current Fedora it hits PEP 668 (externally-managed-environment) anyway. So:
- Missing package? Add the
python3-(orR-, etc.) RPM to the
Containerfile and rebuild the image — don't pip-install at runtime. Prefer Fedora RPMs; they keep the image reproducible and versioned in git.
- No Fedora RPM for it? Add a build-time
RUN pip install …layer to the
Containerfile, baked into the image — never a runtime install in the sandbox.
Rebuild after any change (as the sandbox user — see Install/Troubleshooting):
sudo -u sandbox -H podman build -t mcp-sandbox:latest -f Containerfile .
Output handling
Files written to /sandbox/output/ are returned by reference, not inlined as base64. After a run, the server stages each output under a fresh unguessable token and returns a compact metadata record in place of the bytes:
{ "name": "figure.png", "bytes": 29901, "sha256": "…", "mime": "image/png", "url": "https://host.example/sandbox-out/<token>/figure.png", "expires_in": 3600 }
- Capability URL. Each file is staged at
/<token>/<name>, where<token>
is ~256 bits from a CSPRNG (secrets.token_urlsafe(32)). Possessing the URL is the authorization to fetch it — there is no separate credential.
- Small text is still inlined. Text outputs below 4 KB come back inline; a
round-trip to read three lines isn't worth it. Everything else is referenced.
- Bounded lifetime. Staged files live for a TTL (default 60 min), after
which the GC timer deletes them and the URL 404s — this bounds the exposure window of any leaked URL.
- Integrity. The
sha256lets a consumer verify the bytes, or confirm a
file's identity without fetching it.
Serving the staged outputs
nginx serves the staging directory read-only, with listing, logging, and auth off (the token is the authentication):
location /sandbox-out/ { alias /var/cache/mcp-sandbox/outputs/; auth_basic off; # the capability token is the authorization autoindex off; # non-enumerable: no directory listing access_log off; # keep tokens out of logs add_header X-Robots-Tag "noindex" always; }
On SELinux, the staging dir must carry httpd_sys_content_t, applied before it is populated:
semanage fcontext -a -t httpd_sys_content_t "/var/cache/mcp-sandbox/outputs(/.*)?" restorecon -RFv /var/cache/mcp-sandbox/outputs
Expiry is a systemd .timer firing every 15 min that deletes token directories older than the TTL.
Configuration
HOST=127.0.0.1
PORT=8815
SANDBOX_IMAGE=mcp-sandbox:latest
DEFAULT_TIMEOUT=60
MAX_TIMEOUT=300
# Output-by-reference — REPLACE names with the actual ones from the code:
SANDBOX_PUBLIC_URL=https://host.example # base for capability links
OUTPUT_DIR=/var/cache/mcp-sandbox/outputs # staging directory
OUTPUT_TTL=3600 # seconds; keep in sync with GC timerTroubleshooting
Rebuilt the image but the server still runs the old one? You almost certainly built into the wrong podman store. Containers run rootless as sandbox, which reads its own store under /var/lib/mcp-sandbox/.local/share/containers. An image built as your login user or as root lands in a different store the server never reads — so the build "succeeds" and changes nothing.
Confirm what the service actually sees, and rebuild/load into that store:
sudo -u sandbox -H podman images mcp-sandbox
sudo -u sandbox -H podman build -t mcp-sandbox:latest -f Containerfile .
# or: podman save mcp-sandbox:latest | sudo -u sandbox -H podman loadNo MCP restart is needed afterwards — each run is a fresh --rm container that resolves mcp-sandbox:latest from the sandbox store at launch. Restart the service only when you change the server code or RUNTIMES.
License
Apache-2.0
