跑步箱
通过HTTP传输执行任意shell命令的MCP服务器。专为需要在本地机器或容器内运行命令的AI代理而设计。守护进程在可配置端口上监听，并通过Streamable HTTP和SSE流式传输为MCP协议提供服务。
快速开始
使用 start-run-box.sh
# Build the image
./build.sh
# Start with a single mount directory
./start-run-box.sh /home/user/Code
# Start with multiple mount directories (comma-separated)
./start-run-box.sh /home/user/Code,/home/user/Documents
# Force-restart a running instance on a custom port
./start-run-box.sh -f /home/user/Code 3200
# Verify
curl http://127.0.0.1:3100/health
# {"status":"ok"}直接使用podman
Docker可以用来代替podman——命令是相同的。
# Build the image
./build.sh
# Mount host dirs to the SAME absolute path inside the container
# so the model sees identical paths
podman run --rm -p 3100:3100 \
-v /home/user/Code:/home/user/Code \
localhost/run-box
# Verify
curl http://127.0.0.1:3100/health
# {"status":"ok"}MCP客户端配置
{
"mcpServers": {
"run-box": {
"url": "http://127.0.0.1:3100/mcp"
}
}
}工具： execute
在中运行shell命令 /bin/sh 并返回stdout、stderr和退出代码。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
command | string | ✅ | 要执行的Shell命令 |
cwd | string | ❌ | 工作目录（绝对路径） |
timeout | 编号 | ❌ | 超时（毫秒）（1000–3600000） |
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
PORT | 3100 | 要侦听的TCP端口 |
HOST | 127.0.0.1 | 绑定地址 |
DEFAULT_CWD | /workspace | 默认工作目录 |
DEFAULT_TIMEOUT_MS | 300000 | 默认超时（5分钟） |
MAX_OUTPUT_BYTES | 10485760 | 每个命令的最大输出（10 MB） |
SHUTDOWN_GRACE_MS | 5000 | SIGKILL关闭前的宽限期 |
测试
npm test # all tests
npm run test:unit # unit tests only
npm run test:integration # integration tests only特性
- HTTP传输：用于并发MCP客户端的流式HTTP和SSE流式传输
- 执行命令：运行任何shell命令并获取stdout、stderr、exit代码
- 流媒体：长时间运行的命令的进度通知（通过
_meta.progressToken) - 取消：通过MCP取消飞行中的命令
notifications/cancelled - 超时：可配置每个命令超时，并自动终止进程
- 输出限制：可配置的最大输出大小，带截断指示器
- 容器：使用开发工具（git、curl、build essential）的多阶段Dockerfile
- 卷装载：将主机目录装载到容器中
/workspace - 平滑关闭：SIGTERM/SIGINT处理和进程清理
- 健康检查:
GET /health管弦乐器端点