Sandbox Forge MCP

SandboxForge MCP

SandboxForge MCP是一个用于VM首次隔离执行的MCP服务器，具有工作区感知工具。

它支持多个虚拟化后端：

• 利马在macOS和Linux上
• 本机Windows上的Hyper-V

在每个VM内部，SandboxForge可以引导Docker/Compose工作负载，运行命令，管理可选的MySQL/Redis服务，并通过基于租约的生命周期控制收集工件。

目录

• 为什么选择SandboxForge MCP
• 何时使用此选项（与替代选项相比）
• 主要工作流程
• 隔离模型
• 操作系统支持列表
• 建筑
• 需求
• 快速启动（本地主机运行时）
• 连接您的MCP客户端
• IDE集成示例
• Hello World（第一端到端流）
• 刀具表面
• 配置
• 环境变量
• 发展
• 安全模型和非目标
• 故障排除和错误纠正
• 迁移说明（v1中断）
• 相关文档
• 致谢
• 许可证

为什么选择SandboxForge MCP

• VM优先隔离执行，不应直接在主机上运行
• 感知工作空间的生命周期编排（创建、同步、运行、收集、销毁）
• Docker/在一次性访客中编写运行时
• 跨macOS、Linux/Windows的后端中立合约
• 专为自动化流程和MCP客户端而设计，而不是手动VM管理

何时使用此选项（与替代选项相比）

当您需要用于自动化工作流的工具驱动隔离层时，请选择SandboxForge MCP。

主要工作流程

1. 一次性集成测试沙箱：

- create_instance -> prepare_workspace -> run_command -> collect_artifacts -> destroy_instance

1. 隔离执行不受信任的构建/测试步骤：

- 同步仓库，在客户机中运行构建/测试工具，仅复制输出

1. 带有捆绑服务的Docker化应用程序准备：

- prepare_workspace 带基础设施选项-> docker_compose up ->使用注入的DB/Redis环境运行测试

隔离模型

SandboxForge是VM优先隔离，而不仅仅是Docker主机隔离。

• 隔离边界：一次性VM客户机
• 运行时边界内：Docker/Compose
• 目标：减少主机污染，改善任务执行的隔离

操作系统支持列表

截至2026年3月25日的状态：

返回不支持的主机或缺少先决条件 BACKEND_UNAVAILABLE.

建筑

flowchart LR
  Client["MCP Client"] --> Server["SandboxForge MCP Server"]
  Server --> Backend["Backend (Lima/Hyper-V)"]
  Backend --> VM["Disposable VM Guest"]
  VM --> Runtime["Docker/Compose Workloads"]
  Runtime --> Artifacts["Logs / Artifacts / Results"]

高级运行时流程：

1. 客户端通过stdio或Streamable HTTP调用工具
2. LeaseService 验证配置和生命周期约束
3. LeaseStore 在SQLite中保持租约/任务状态
4. 后端执行VM生命周期操作
5. 运行时助手在客户机中运行命令和容器工作负载
6. 清扫器通过TTL过期租约

关键模块：

• src/lima_mcp_server/server.py：MCP运输和工具登记
• src/lima_mcp_server/service.py：编排和响应塑造
• src/lima_mcp_server/backend/lima.py：Lima后端适配器
• src/lima_mcp_server/backend/hyperv.py：Hyper-V后端适配器
• src/lima_mcp_server/backend/factory.py：后端选择(auto|lima|hyperv)
• src/lima_mcp_server/workspace_config.py：配置解析/验证
• src/lima_mcp_server/runtime.py：Docker/Compose命令构建器
• src/lima_mcp_server/db.py：SQLite持久性

需求

• python 3.11+
• uv
• 主机虚拟化先决条件：

- macOS/Linux： limactl 在 PATH - Windows:Hyper-V cmdlet+ ssh/scp

最小默认VM形状：

• cpus = 1
• memory_gib = 2.0
• disk_gib = 15.0

快速启动（本地主机运行时）

uv sync --extra dev
uv run sandboxforge-mcp-server

如果您的shell无法解析脚本入口点：

uv run python -m lima_mcp_server.server

使用Make：

make setup
make run

连接您的MCP客户端

选项A：本地stdio（建议开发）

在MCP客户端配置中使用以下内容：

{
  "mcpServers": {
    "sandboxforge": {
      "command": "uv",
      "args": ["run", "sandboxforge-mcp-server"],
      "cwd": "/absolute/path/to/SandboxMCP"
    }
  }
}

如果你的客户仍然报告 Failed to spawn sandboxforge-mcp-server，使用：

{
  "mcpServers": {
    "sandboxforge": {
      "command": "uv",
      "args": ["run", "python", "-m", "lima_mcp_server.server"],
      "cwd": "/absolute/path/to/SandboxMCP"
    }
  }
}

选项B：流式HTTP

运行启用HTTP的服务器（默认）并连接到：

• 网址： http://127.0.0.1:8765/mcp

客户端配置示例：

{
  "mcpServers": {
    "sandboxforge-http": {
      "transport": "streamable-http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

笔记：

• http://127.0.0.1:8765/ 回报 404 刻意为之
• http://127.0.0.1:8765/mcp 是MCP端点

IDE集成示例

集成参考：

• 安装指南
• 示例工作区演练
• 模型上下文协议
• 光标文档

光标（标准输入模式）

当Cursor应启动服务器进程时使用：

{
  "mcpServers": {
    "sandboxforge": {
      "command": "uv",
      "args": ["run", "sandboxforge-mcp-server"],
      "cwd": "/absolute/path/to/SandboxMCP"
    }
  }
}

如果入口点解析失败，则回退：

{
  "mcpServers": {
    "sandboxforge": {
      "command": "uv",
      "args": ["run", "python", "-m", "lima_mcp_server.server"],
      "cwd": "/absolute/path/to/SandboxMCP"
    }
  }
}

游标或多个IDE（推荐使用共享HTTP服务器）

当多个客户端/代理必须共享一台服务器并避免重复实例时使用：

1. 在主机上启动服务器一次：

cd /absolute/path/to/SandboxMCP
uv run python -m lima_mcp_server.server

1. 将每个IDE/客户端指向同一端点：

{
  "mcpServers": {
    "sandboxforge": {
      "transport": "streamable-http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

其他与MCP兼容的IDE/客户端

使用相同的JSON格式(mcpServers)其中之一：

• command + args （stdio），或
• transport: "streamable-http" + url （共享服务器）

这使得Cursor和支持MCP的其他IDE扩展/代理之间的集成保持一致。

Hello World（第一端到端流）

连接客户端后，在本地工作区路径上运行此流：

1. validate_workspace_config(workspace_root="/abs/path/to/workspace")
2. create_instance(workspace_root="/abs/path/to/workspace", auto_bootstrap=true, wait_for_ready=true)
3. prepare_workspace(instance_id="", wait_for_ready=true)
4. run_command(instance_id="", command="echo hello-from-sandbox && uname -a")
5. destroy_instance(instance_id="")

预期成功标志：

• create_instance：返回 instance_id 以及后端详细信息
• prepare_workspace: runtime_ready = true
• run_command：退出代码 0 带命令输出

刀具表面

核心工具包括：

• create_instance, list_instances, destroy_instance, extend_instance_ttl
• validate_workspace_config, validate_image
• prepare_workspace, run_command
• copy_to_instance, copy_from_instance, sync_workspace_to_instance, sync_instance_to_workspace
• docker_build, docker_run, docker_exec, docker_logs, docker_compose, docker_ps, docker_images, docker_cleanup
• start_background_task, get_task_status, get_task_logs, stop_task
• collect_artifacts

配置

工作区配置文件优先级（高->低）：

1. 请求覆盖
2. /.sandboxforge.toml
3. ~/.config/sandboxforge-mcp/config.toml
4. 内置默认值

仍然支持旧配置文件：

• 工作区： .orbitforge.toml, .lima-mcp.toml
• 全球的： ~/.config/orbitforge-mcp/config.toml, ~/.config/lima-mcp/config.toml

默认VM配置：

• template = "template:docker"
• vm_type = "vz" 在macOS上
• vm_type = "qemu" 在Linux上
• vm_type = null 在其他主机上

有关架构/示例，请参见 docs/SETUP.md 和 src/lima_mcp_server/workspace_config.py.

环境变量

核心服务器：

• MCP_HTTP_HOST （默认值 127.0.0.1)
• MCP_HTTP_ALLOW_NON_LOOPBACK （默认值 0)
• MCP_HTTP_PORT （默认值 8765)
• MCP_ENABLE_HTTP （默认值 1)
• LEASE_DB_PATH （默认值 state/leases.db)
• MAX_INSTANCES （默认值 3)
• DEFAULT_TTL_MINUTES （默认值 30)
• MAX_TTL_MINUTES （默认值 120)
• SANDBOX_SWEEPER_INTERVAL_SECONDS （默认值 60)

后端选择：

• SANDBOX_BACKEND (auto, lima, hyperv；默认 auto)

Hyper-V后端：

• HYPERV_SWITCH_NAME （默认值 Default Switch)
• HYPERV_BASE_VHDX （Hyper-V需要）
• HYPERV_STORAGE_DIR （默认值 state/hyperv)
• HYPERV_SSH_USER （默认值 ubuntu)
• HYPERV_SSH_KEY_PATH （可选）
• HYPERV_SSH_PORT （默认值 22)
• HYPERV_BOOT_TIMEOUT_SECONDS （默认值 180)

发展

运行测试：

uv run pytest -q

集成门：

• RUN_LIMA_INTEGRATION=1
• RUN_HYPERV_INTEGRATION=1

安全模型和非目标

信任模型：

• 可信任：主机操作员、MCP服务器进程、后端工具
• 不可信/不太可信：在来宾VM中执行的工作区代码和命令

威胁模型重点：

• 减少任务执行对主机的直接暴露
• 通过在一次性访客中运行工作负载来限制主机污染
• 通过持久的租约/任务记录保持任务生命周期的可审计性

非目标：

• 不保证客户机到主机内核逃逸
• 不能替代强化的多租户沙盒基础设施
• 默认情况下不是一个完整的网络隔离框架

故障排除和错误纠正

Failed to spawn: sandboxforge-mcp-server

• 跑 uv sync --extra dev 在repo根目录中
• 验证脚本： uv run sandboxforge-mcp-server --help
• 回退入口点： uv run python -m lima_mcp_server.server
• 确保客户 cwd 指向此回购根

BACKEND_UNAVAILABLE

• 确认主机操作系统的后端先决条件
• 检查所选后端(SANDBOX_BACKEND)
• macOS/Linux：验证 limactl --version
• Windows：验证 Get-Command New-VM, Get-Command New-VHD, ssh -V

INSUFFICIENT_HOST_RESOURCES

• create_instance 现在运行CPU、可用内存和可用磁盘的主机容量预检
• 如果飞行前失败，减少 vm.cpus, vm.memory_gib，或 vm.disk_gib 在 /.sandboxforge.toml
• 在低规格主机上，从 auto_bootstrap=false 并呼叫 prepare_workspace(..., include_services=false) 减少启动开销

不支持Docker托管的MCP运行时

• 直接在主机操作系统（macOS/Linux/Windows本机）上运行MCP服务器
• 将Docker的使用保持在访客VM工作负载内(docker_* 工具），而不是作为服务器主机运行时

HTTP端点混淆

• GET / 回报 404 （预计）
• MCP端点为 /mcp
• 406 Not Acceptable 在纯curl上意味着端点是活动的，但需要MCP可流式传输的HTTP标头

使用了弃用的环境变量名称

• 替换 LIMA_SWEEPER_INTERVAL_SECONDS 和 SANDBOX_SWEEPER_INTERVAL_SECONDS

迁移说明（v1中断）

此版本使用后端中性API命名。

与v1之前的版本相比发生了重大变化：

• 工具重命名： lima_validate_image -> validate_image
• 响应/存储字段重命名： lima_name -> backend_instance_name
• 错误代码重命名： LIMA_COMMAND_FAILED -> BACKEND_COMMAND_FAILED
• 环境变量重命名： LIMA_SWEEPER_INTERVAL_SECONDS -> SANDBOX_SWEEPER_INTERVAL_SECONDS

示例工作区

对于可复制的真实工作空间设置：

• examples/sample-workspace/
• examples/sample-workspace/README.md
• examples/sample-workspace/.sandboxforge.toml

相关文档

• 设置： docs/SETUP.md
• 项目结构： docs/PROJECT_STRUCTURE.md
• 编码约束： docs/CODING_STANDARDS.md
• 贡献者指南： CONTRIBUTING.md
• 变更日志： CHANGELOG.md
• 安全： SECURITY.md
• 代理商定位： AGENTS.md

致谢

• 模型上下文协议 为开放协议基础。
• Python MCP SDK 为服务器/工具布线提供动力。
• 利马 Lima后端使用的macOS/Linux VM生命周期原语。
• 微软Hyper-V 以及Windows后端使用的OpenSSH工具。
• 码头工人 和 用于客户机工作负载运行时。
• 紫外线 用于快速Python环境和工作流管理。

许可证

MIT。看 LICENSE.