Sandbox Env MCP

sandbox-mcp

MCP server that gives AI agents a real working environment: persistent shells, a filesystem, and multi-machine management — backed by Docker containers or remote SSH hosts.

Features

• Persistent shells — stateful bash or PowerShell sessions that survive across tool calls. Set env vars, activate venvs, change directories, and they stay.
• Multi-machine — manage several Docker containers and SSH hosts simultaneously. Each has its own isolated workspace and shell pool.
• Full filesystem access — read, write, patch, and search files on any target machine. All writes are atomic (temp-file + rename).
• Zero-config startup — creates a default Docker container automatically on first run. One command, ready to go.
• Progressive discovery — env tool exposes capabilities step by step. Agents call env(action="help") to see what's available.
• Docker lifecycle — create, stop, start, restart, remove containers. Build images, inspect configs, commit state, view logs.
• SSH remote access — connect to Linux and Windows machines over SSH. Windows targets get automatic code-page probing.
• Safety net — sensitive-path warnings (.ssh, .aws, .env*) without blocking access. Pre-write syntax lint for JSON/YAML/TOML.
• Audit trail — every tool call is logged with timestamps, parameters, and outcomes. Queryable from within the agent session.

Quick start

pip install sandbox-env-mcp
# stdio — for Claude Desktop, Cline, Continuesandbox-mcp
# HTTP — for remote agentssandbox-mcp-http

On first run a default container (python:3.14-slim, named admin) starts automatically with a persistent bash shell. No other setup.

Requirements: Python 3.12+, Docker SDK, running Docker daemon. SSH mode needs openssh-client.

Tools

All tools target the default machine unless an explicit machine parameter is passed.

audit_query is exposed when the audit log is a SQLite database — it lets the agent search historical tool calls.

Shell states

Every shell is in one of four states:

Key shell_exec parameters:

• wait (default true): block until the command completes.
• timeout (default 10 s): on expiry returns status="waiting" with a hint to switch to wait=false + shell_read for long-running commands.
• max_output (default 50000 bytes): caps returned output; excess is shown as the tail (last N bytes).

env actions

env(action="help") lists what's available. env(action="help", topic="<action>") returns full docs for a specific action.

Always available

Docker

SSH

Available when [ssh.targets] is configured.

File operations

Safety warnings are surfaced for sensitive paths (.ssh, .aws, .env*, /etc/shadow, etc.) — advisory only, agents still have full access. Writes to .json, .yaml, .yml, .toml are syntax-checked before writing (fail-closed).

Configuration

Config lives at ~/.sandbox-mcp/config.toml (copy config/config.example.toml). Every field can be overridden with SANDBOX_MCP_<SECTION>_<KEY> env vars.

[server]port = 8010auth_tokens_file = "~/.sandbox-mcp/auth_tokens"
[storage]work_home = "/var/lib/sandbox-mcp"
[docker]default_image = "python:3.14-slim"auto_network = "sandbox-mcp"      # "" = noneadmin_machine = "admin"           # "" = no /host mounthost = ""                         # "" = from Docker environment
[ssh]connect_timeout = 10[ssh.targets.win-build]host = "192.168.1.100"user = "builder"os_type = "windows"
[default_machine]enabled = truebackend = "docker"name = "admin"
[shell]default_max_output = 50000
[files]max_file_size = 51200

Backends

Docker

Containers get bind mounts for workspace isolation:

• work_home/<name>/ → /workspace (rw)
• work_home/<share_subdir>/ → /share/ (ro, shared across peers)
• work_home/<share_subdir>/<name>/ → /share/<name>/ (rw overlay)

When a container's name matches admin_machine, it also gets work_home/ → /host (rw) — a global view of all workspaces.

Server startup auto-reconciles with the Docker daemon: surviving containers are re-adopted into the registry.

SSH

Connects over SSH with ControlMaster for connection reuse. Windows targets get automatic code-page probing and encoded-command execution.

Deployment

# docker-compose.ymlservices:  sandbox-mcp:    image: ghcr.io/hs3434/sandbox-env-mcp:latest    network_mode: host    volumes:      - /var/run/docker.sock:/var/run/docker.sock      - /var/lib/sandbox-mcp:/var/lib/sandbox-mcp      - ./config:/root/.sandbox-mcp

HTTP mode reads bearer tokens from auth_tokens_file (hot-reload on every request). If the file is empty or missing and auto_generate_if_empty=true, a random token is printed to stderr at startup.

Audit

Every tool call is recorded: timestamp, machine, action, status, duration, and hashed parameters. Defaults to SQLite at ~/.sandbox-mcp/audit.db. Set log_path="" for JSON-line stderr output instead.