agent-sandbox

agent-sandbox

An MCP (Model Context Protocol) server that routes shell commands to either the host machine or a Docker Compose container, based on operator-configured allow patterns.

Install

go install github.com/ynagai/mcp-command-router@latest

Configuration

Copy config.example.toml to config.toml and edit:

[server]
output_dir = "/tmp/mcp-output"
container_target = "app"

[allow_patterns]
patterns = [
  "git *",
  "make *",
]

Usage

Start the project sandbox from your project root:

agent-sandbox sandbox-up -d --config agent-sandbox.toml

Start the MCP server:

agent-sandbox command-router --config agent-sandbox.toml

Stop the current project sandbox:

agent-sandbox sandbox-down --config agent-sandbox.toml

Remove all Docker containers and networks that appear to be managed by agent-sandbox:

agent-sandbox sandbox-prune

sandbox-prune is destructive. It removes every container labeled cr.managed=true and every Docker network whose name starts with cr-sandbox-.

Check whether external dependencies are usable on this host:

agent-sandbox doctor

doctor verifies that nono is on PATH, that docker compose version works (which also accepts compatible CLIs like colima or podman that alias docker), and that the Docker daemon is reachable. Exits 0 when all checks pass, 1 otherwise.

Register as an MCP tool in your Claude Code settings.

How It Works

• Commands matching an allow pattern are executed on the host (after shell-safety validation)
• All other commands are routed to the configured Docker Compose service
• Output is always written to separate stdout/stderr files; the MCP response returns file paths and exit code only