nanosandbox-mcp

An MCP server that lets an AI agent run commands in a nanosandbox sandbox. It speaks MCP over stdio and offers one tool, run_command.

Install

npx -y nanosandbox-mcp --help        # npm, nothing to install first
uvx nanosandbox-mcp --help           # PyPI, via uv
cargo install nanosandbox-mcp        # crates.io, builds from source

Prebuilt binaries cover macOS (Apple silicon and Intel) and Linux (x86_64 and aarch64, glibc 2.17+). Linux and macOS only. Windows isn't supported yet: the sandbox there is a resource limiter, not a security boundary.

Use

Add it to an MCP client's configuration (Claude Desktop, Cursor, Zed, ...):

{
  "mcpServers": {
    "sandbox": {
      "command": "npx",
      "args": ["-y", "nanosandbox-mcp", "--workspace", "/path/to/project"]
    }
  }
}

(With uvx: "command": "uvx", "args": ["nanosandbox-mcp", "--workspace", ...]. With a cargo installed binary: "command": "nanosandbox-mcp".)

The agent can now run programs, with their files limited to that workspace and no network.

Who decides what the sandbox may do

You do, when you launch the server. The model chooses what to run; it never chooses what the sandbox may touch. The tool takes only command, args and stdin. There is no parameter for paths, network, memory or time, so a model can't ask for more than you allowed. An extra argument is refused.

Run nanosandbox-mcp --help for the full text. A limit this platform can't enforce (for example --max-pids on macOS) makes the server refuse to start, rather than run without it.

The tool

run_command runs one program in a fresh sandbox and returns:

{ "stdout": "...", "stderr": "...", "exit_code": 0, "duration_ms": 15,
  "timed_out": false, "out_of_memory": false, "cpu_limit_hit": false,
  "tmp_limit_hit": false, "output_truncated": false, "blocked_hosts": [] }

A command that runs and fails (non-zero exit, killed by a limit) is a normal result, so the model can read the output and react. Only a call that couldn't run at all comes back with isError.

There is no shell: args is the argument vector. For pipes or &&, run sh with ["-c", "..."]. Every call is a new sandbox; files in the workspace are what carry over. Calls run in parallel up to --max-concurrent. A client cancelling a call stops its reply, but the command runs until it ends or hits the time limit.

One line per call goes to stderr (command, exit code, duration, which limit hit, blocked hosts). Stdin and output are only logged with --log-io, since they can contain secrets.

Protocol

Stdio transport, tools only. Both generations of the protocol are served on the same stream: the stateless 2026-07-28 revision (server/discover, per-request _meta) and the earlier initialize handshake (2025-11-25 down to 2024-11-05). HTTP, OAuth, resources, prompts and sampling are not offered: a local command runner has no use for them.

What this isn't

This is a process-level sandbox on a shared kernel, suited to one developer's agent or one trusted service. It is not isolation between mutually distrusting tenants. Read the threat model before relying on it, including the platform differences: macOS is structurally weaker than Linux.

Running as root on Linux, commands run as nobody unless --host-uid/--host-gid say otherwise, and the workspace must be writable by that user; the server says so at startup if it isn't. On Ubuntu 23.10+ under AppArmor's unprivileged_userns restriction, --allow-network is refused at startup, and /var/tmp and /dev/shm are the host's shared paths.