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)