bash-sandbox-mcp

MCP server exposing a single bash tool backed by just-bash's OverlayFs. Agents run bash against the current project — reads come from disk, writes stay in memory, and real files are never modified.

Install

npx bash-sandbox-mcp [OPTIONS]

Quick Start

Zero flags works against the current directory. Configure with any MCP client over stdio (e.g. Claude Code, Cursor):

{
  "mcpServers": {
    "bash": {
      "command": "npx",
      "args": ["bash-sandbox-mcp"]
    }
  }
}

CLI Reference

| Flag | Short | Default | Description | |---|---|---|---| | --root <path> | | current directory | Project root | | --cwd <path> | | overlay mount point | Working directory in the sandbox | | --allowed-url-prefix <url\|json> | -u | (none) | Allowed URL prefix; repeatable | | --allowed-methods <method,...> | -m | GET,HEAD | Comma-separated HTTP methods | | --dangerously-allow-full-network | | off | Allow all URLs and methods (DANGEROUS) | | --python | | off | Enable python3/python commands | | --javascript | | off | Enable js-exec command | | --timeout <ms> | | 30000 | Per-call timeout (max: 300000) | | --max-commands <n> | | 10000 | Max commands per exec | | --max-loop-iters <n> | | 10000 | Max loop iterations | | --max-call-depth <n> | | 100 | Max function recursion depth | | --help | -h | | Show help and exit |

Network Access

Network access is off by default. The curl command only exists when network is configured.

Allow-list with default methods (GET, HEAD)

bash-sandbox-mcp --allowed-url-prefix "https://api.github.com/repos/myorg/" \
              -u "https://api.example.com"

Allow-list with explicit methods and header injection

bash-sandbox-mcp --allowed-url-prefix "https://api.example.com" \
              -u '{"url":"https://my.site.com/my/api","headers":{"Authorization":"Bearer secret"}}' \
              -m GET,HEAD,POST

Headers specified via the JSON object form are injected at the fetch boundary — they never appear inside the sandbox, so credentials stay hidden from the agent.

Full network access (dangerous)

bash-sandbox-mcp --dangerously-allow-full-network

Security Model

• Overlay filesystem: Reads come from the real project directory; writes stay in memory and are discarded on process exit. Real files are never modified.
• Network off by default: Must be explicitly enabled via allow-lists or the dangerous full-access flag.
• Header injection boundary: Headers in the JSON object form are applied at the fetch layer and override any user-supplied headers with the same name, preventing credential substitution from inside the sandbox.
• Execution limits: Configurable limits prevent infinite loops, deep recursion, and resource exhaustion.
• No VM isolation: Execution runs in-process without VM isolation. See just-bash's security model for details.

License

MIT (see LICENSE)