使用说明
Persistent, container-backed sandboxes over MCP (HTTP + SSE)
是什么 mcp-sandboxd?
mcp-sandboxd 是一个兼容MCP的服务器，允许在Docker或Kubernetes中的隔离沙盒内运行任意命令。
核心思想很简单： 标识符 （例如对话id）映射到跨运行重用的长时间运行的沙盒环境。这使得代理工作流感觉像一个“实机”，而不会暴露你的主人。
用例
- 长期运行的沙盒：安装deps一次，迭代速度快。
- IDE集成：通过MCP从编辑器运行test/lint/build，而不会污染您的机器。
- 代理执行后端：给代理一个运行shell命令的地方。
- 工件代理：在内部生成文件
/artifacts并通过服务器HTTP端点下载它们。
工具
run_sandbox：在按以下键键入的沙箱中运行一个或多个命令identifier.delete_sandbox：删除沙盒环境。restart_sandbox：为标识符重新创建一个新的沙盒。
人工制品
在沙盒中写入文件 /artifacts运行完成后，服务器将工件从沙箱复制到 ARTIFACTS_DIR 并通过HTTP为它们提供服务。
从MCP客户端的角度来看，本地Docker、Docker中的Docker和Kubernetes原生后端也是如此：客户端总是通过 GET /artifacts/... 永远不要直接与沙盒文件系统交谈。
- 按运行id:
GET /artifacts/<identifier>/<run_id>/<path> - 便利别名：
GET /artifacts/<identifier>/latest/<path>
快速入门（本地Docker）
make docker-build-sandbox
cp .env.example .env
make dev
这将启动服务器 http://localhost:8080.
- MCP JSON-RPC端点：
http://localhost:8080/mcp - SSE流（每次运行）：
http://localhost:8080/mcp/events?run_id=...
MCP客户端配置
下面是通过HTTP+SSE连接到正在运行的服务器的示例配置。
OpenCode
// ~/.config/opencode/config.json
{
"mcpServers": {
"mcp-sandboxd": {
"type": "sse",
"url": "http://localhost:8080/mcp"
}
}
}
Claude / Claude Desktop (Remote MCP connector)
添加自定义连接器并将其指向正在运行的服务器。
- 网址：
http://localhost:8080/mcp（或您部署的https://.../mcp)
Run via Docker (talking to host Docker socket)
开始 mcp-sandboxd 上 http://localhost:8080/mcp.
{
"mcpServers": {
"mcp-sandboxd": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-p",
"8080:8080",
"-e",
"PORT=8080",
"-e",
"MCP_PATH=/mcp",
"-e",
"SANDBOX_BACKEND=docker",
"-e",
"SANDBOX_IMAGE=ghcr.io/jeliasson/mcp-sandboxd-sandbox:latest",
"-v",
"/var/run/docker.sock:/var/run/docker.sock",
"ghcr.io/jeliasson/mcp-sandboxd:latest"
]
}
}
}
文档
将军
后端
- 发展：本地工作流程和制定目标。
- 码头工人：Docker套接字设置和DinD模式。
- Kubernetes：Kubernetes原生后端和DinD sidecar。
安全说明
no-new-privileges默认情况下启用；sudo在沙盒中无法工作。- 使用
run_sandbox.options.as_user="root"用于行政操作。 - 更喜欢跑步
mcp-sandboxd在具有默认拒绝出口的专用命名空间中。
