Sandbox Env MCP

sandbox-mcp

为 AI Agent 提供真实工作环境的 MCP 服务：持久化 Shell、文件系统和多机器管理，底层由 Docker 容器或远程 SSH 主机提供支持。

功能

• 持久化 Shell — 有状态的 bash 或 PowerShell 会话，可跨工具调用继续使用。设置环境变量、激活 venv、更改目录后，这些状态都会保留。
• 多机器 — 同时管理多个 Docker 容器和 SSH 主机。每台机器都有独立的工作区和 Shell 池。
• 完整文件系统访问 — 在任意目标机器上读取、写入、修补和搜索文件。所有写入均为原子操作（临时文件 + 重命名）。
• 零配置启动 — 首次运行时自动创建默认 Docker 容器。一条命令即可就绪。
• 渐进式发现 — env 工具逐步展示可用功能。Agent 可调用 env(action="help") 查看可用内容。
• Docker 生命周期管理 — 创建、停止、启动、重启和移除容器。构建镜像、检查配置、提交状态、查看日志。
• SSH 远程访问 — 通过 SSH 连接 Linux 和 Windows 机器。Windows 目标机器会自动探测代码页。
• 安全防护 — 对敏感路径（.ssh、.aws、.env*）发出警告，但不阻止访问。写入前对 JSON/YAML/TOML 进行语法检查。
• 审计记录 — 记录每次工具调用的时间戳、参数和结果。可在 Agent 会话中查询。

快速开始

pip install sandbox-env-mcp

# stdio — for Claude Desktop, Cline, Continue
sandbox-mcp

# HTTP — for remote agents
sandbox-mcp-http

首次运行时，会自动启动默认容器（python:3.14-slim，名称为 admin），并提供持久化 bash Shell。无需其他设置。

要求：Python 3.12+、Docker SDK、正在运行的 Docker 守护进程。 SSH 模式需要 openssh-client。

工具

除非显式传入 machine 参数，否则所有工具均面向默认机器。

工具	功能
shell_exec	在持久化 Shell 中运行命令。阻塞等待命令完成（wait=true，超时 10 秒），或使用 wait=false 直接返回。
shell_read	读取运行中或已完成命令的缓冲输出。
shell_new	在机器上创建新的 Shell。返回 shell_id。
shell_remove	按 shell_id 终止并移除 Shell。
shell_list	列出所有 Shell 及其状态、所属机器、运行时间和最后一条命令。
write_stdin	向运行中的 Shell 写入原始字节 — 使用 Ctrl-C（\x03）中断，或向 read / Read-Host 等交互式程序输入内容。在 Windows/PowerShell 上不支持 Ctrl-C（管道模式没有终端驱动）；请改为终止 Shell。
machine_list	列出所有已注册机器及其后端、状态、用途和 Shell 数量。
default_set	设置默认机器，或设置某台机器的默认 Shell。
file_read	按行号读取文件。支持通过 offset + limit 分页。
file_write	以原子方式写入内容。自动创建父目录。
file_patch	通过模糊匹配进行定点编辑。mode=replace（查找并替换）或 mode=patch（统一差异格式）。
file_search	搜索文件内容（ripgrep）或查找文件（glob）。按修改时间排序。
env	渐进式发现入口。请从 env(action="help") 开始。

当审计日志使用 SQLite 数据库时，会提供 audit_query — 它可让 Agent 搜索历史工具调用。

Shell 状态

每个 Shell 都处于以下四种状态之一：

状态	含义	Agent 可以执行的操作
init	Shell 刚创建，正在启动。10 秒后超时并进入 terminated 状态。	等待 — Shell 就绪前，shell_exec 会返回错误。
ready	已显示提示符，正在等待命令。	发送命令、读取输出、写入 stdin。
waiting	命令正在运行。	使用 shell_read 轮询输出。使用 write_stdin 发送 Ctrl-C。
terminated	Shell 进程已退出（因信号、退出、超时或管道中断）。最后的输出会保留。	读取剩余输出，然后使用 shell_remove + shell_new 继续。默认 Shell 不会自动替换。

shell_exec 的关键参数：

• wait（默认 true）：阻塞，直到命令完成。
• timeout（默认 10 秒）：超时后返回 status="waiting" 和提示，建议对长时间运行的命令切换为 wait=false + shell_read。
• max_output（默认 50000 字节）：限制返回的输出大小； 超出部分将显示末尾内容（最后 N 个字节）。

env 操作

env(action="help") 会列出可用操作。env(action="help", topic="<action>") 会返回特定操作的完整文档。

始终可用

操作	参数	描述
help	topic?	列出操作或获取某项操作的文档。
status	—	默认机器、机器列表、Shell 列表。
list_targets	—	配置中的预定义 SSH 目标。
machine_list	—	已注册的机器。
shell_list	machine?	Shell 列表，可按机器筛选。
shell_new	machine?, purpose?	新建 Shell 会话。
shell_remove	shell_id	终止并移除。
default_set	machine 或 shell_id	设置默认机器或 Shell。

Docker

操作	必需参数	描述
docker_run	name, image, purpose	创建/启动容器。名称冲突时会重新连接。
docker_ps	—	列出受管理的容器。
docker_images	—	列出守护进程上的所有镜像。
docker_image_history	image	逐层显示构建历史。
docker_build	image_tag, machine	使用 /workspace 中的 Dockerfile 构建。
docker_commit	machine, image_tag	将容器提交为新镜像。
docker_stop	machine	停止（保留状态）。
docker_start	machine	启动已停止的容器。
docker_remove	machine	停止并移除容器及其 Shell。
docker_inspect	machine	精简配置。对于镜像，使用 kind=image。
docker_logs	machine	查看日志，可使用 tail、since、until。
docker_diff	machine	查看相对于镜像的文件系统变更。
docker_stats	machine	CPU/内存/网络/IO 快照。
docker_restart	machine	停止 + 启动 + 验证。

SSH

操作	必需参数	描述
connect	name	连接到已配置的目标。
close	name	断开连接并注销。

配置 [ssh.targets] 后即可使用。

文件操作

工具	关键参数	说明
file_read	path, offset, limit	按行编号。文件超过 50 KB 时会拒绝读取并提供提示。
file_write	path, content	原子操作（临时文件 + 重命名），自动创建父目录，并在写入后验证。
file_patch	path, old_string, new_string（替换模式）或 patch（统一差异格式）	模糊匹配。保留 BOM 和行结束符。
file_search	pattern, search_type, path, file_glob, limit	由 ripgrep 提供支持。结果按修改时间排序。

对于敏感路径（.ssh、.aws、.env*、/etc/shadow 等），会显示安全警告 — 仅供参考，Agent 仍拥有完整访问权限。写入 .json、.yaml、.yml、.toml 文件前会进行语法检查（检查失败则拒绝写入）。

配置

配置位于 ~/.sandbox-mcp/config.toml（复制 config/config.example.toml）。每个字段都可以通过 SANDBOX_MCP_<SECTION>_<KEY> 环境变量覆盖。

[server]
port = 8010
auth_tokens_file = "~/.sandbox-mcp/auth_tokens"

[storage]
work_home = "/var/lib/sandbox-mcp"

[docker]
default_image = "python:3.14-slim"
auto_network = "sandbox-mcp"      # "" = none
admin_machine = "admin"           # "" = no /host mount
host = ""                         # "" = from Docker environment

[ssh]
connect_timeout = 10
[ssh.targets.win-build]
host = "192.168.1.100"
user = "builder"
os_type = "windows"

[default_machine]
enabled = true
backend = "docker"
name = "admin"

[shell]
default_max_output = 50000

[files]
max_file_size = 51200

后端

Docker

容器会获得绑定挂载，以隔离工作区：

• work_home/<name>/ → /workspace（读写）
• work_home/<share_subdir>/ → /share/（只读，在各节点间共享）
• work_home/<share_subdir>/<name>/ → /share/<name>/（读写覆盖层）

当容器名称与 admin_machine 匹配时，还会挂载 work_home/ → /host（读写），以全局查看所有工作区。

服务启动时会自动与 Docker 守护进程协调：重新接管仍在运行的 容器并将其纳入注册表。

SSH

通过 SSH 连接，并使用 ControlMaster 重用连接。Windows 目标会自动探测代码页并执行编码后的命令。

部署

# docker-compose.yml
services:
  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 模式会从 auth_tokens_file 读取承载令牌（每次请求时热重载）。如果文件为空或不存在，且 auto_generate_if_empty=true，启动时会将随机令牌打印到 stderr。

审计

每次工具调用都会被记录：时间戳、机器、操作、状态、 耗时和经过哈希处理的参数。默认使用 SQLite，数据库位于 ~/.sandbox-mcp/audit.db。设置 log_path=""，即可改为向 stderr 输出 JSON 行。