MCP Sandbox Computer VM for AI

面向 AI 的 MCP 沙盒计算机 VM

为 AI Agent 提供可命名、可管理的 Linux 计算机 — 通过 MCP

MCP Sandbox Computer VM for AI 是 Kilntainers 的一个专注于生命周期管理的分支。它为 Agent 提供隔离的 Linux 计算机、稳定 ID、临时或持久的生命周期、交互式 MCP App 仪表板，以及一流的 Docker 和 Fly Machines 后端。

• 🖥️ MCP App 仪表板： 在 FLUJO 或其他稳定的 MCP Apps 宿主中列出计算机、运行命令、重启、恢复出厂设置和删除计算机。
• 🏷️ 命名计算机： 使用稳定的 computer_id 重新连接，或省略该参数以获取易读的随机标识名。
• 💾 明确的生命周期： 临时计算机会随 MCP 会话结束而移除；永久计算机会一直保留，之后可重新连接。
• 🧰 多个后端： Docker/Podman、本机 Fly Machines、Modal、E2B 和 WebAssembly。
• 🏝️ 按 Agent 隔离： 每个 Agent 都有自己的专用沙盒 — 不共享状态，也不会相互污染。
• 🔒 安全为设计核心： Agent 通过 MCP 与沙盒通信 — 而不是在沙盒内部运行。沙盒不会接触到 Agent API 密钥、代码或提示词。
• 🔌 工具和 UI 访问： terminal_execute 保持简单，而可选的提供商无关生命周期工具可同时为模型和仪表板提供支持。
• 📈 可扩展： 从笔记本电脑上的少数 Agent 扩展到云中并行运行的数千个 Agent。

为什么需要沙盒计算机？

Agent 已经非常擅长使用终端，并且借助 grep、find、jq 和 awk 等常见 Linux 工具，可以节省数千个 token。让 Agent 访问主机操作系统很危险，而配置大量隔离环境在运维上又十分繁琐。MCP Sandbox Computer VM for AI 为每个 Agent 提供一个具有明确生命周期的专用沙盒。

快速开始

直接从 PyPI 运行已发布的软件包。默认使用 Docker 和 stdio：

uvx mcp-sandbox-computer-vm-for-ai

将其添加到 Claude Code：

claude mcp add --scope user sandbox-computer -- uvx mcp-sandbox-computer-vm-for-ai

或者将其添加到 Claude Desktop 等基于 JSON 的 MCP 客户端：

{
  "mcpServers": {
    "sandbox-computer": {
      "command": "uvx",
      "args": ["mcp-sandbox-computer-vm-for-ai"]
    }
  }
}

默认情况下，服务仅公开 terminal_execute。启动服务前设置 ENABLE_LIFECYCLE_TOOLS=true，即可公开 computer_* 工具和 MCP App 仪表板。对于基于 JSON 的 stdio 客户端，请将其添加到服务配置中：

{
  "env": {
    "ENABLE_LIFECYCLE_TOOLS": "true"
  }
}

然后调用 computer_dashboard 打开 App。仪表板不依赖外部浏览器。其内部资源 URI 仍为 ui://kilntainers/computers，以兼容上游实现。

命名计算机生命周期

terminal_execute 接受另外两个可选输入：

• computer_id：长度为 1–63 个字符的小写 slug。首次调用时如果未提供，该调用会创建一个易读的随机 ID，并将其用作该 MCP 会话的默认 ID。
• temporary：默认为 true。临时计算机会在所属 MCP 会话关闭时移除。将其设为 false，即可让计算机在服务／会话关闭后继续存在，并可稍后通过 ID 重新连接。

每个执行结果都会在 stdout、stderr、退出代码和耗时旁包含 computer_id 和 temporary：

{
  "computer_id": "steady-otter-a31f",
  "temporary": false,
  "stdout": "persistent\n",
  "stderr": "",
  "exit_code": 0,
  "exec_duration_ms": 84
}

生命周期工具与提供方无关，且仅在 ENABLE_LIFECYCLE_TOOLS=true 时启用：

工具	用途
computer_dashboard	打开 MCP App 并返回当前清单
computer_list	列出状态、后端、映像、提供方 ID 和生命周期模式
computer_create	按 ID 创建／连接；不提供 ID 时始终生成新的 slug
computer_restart	重启，同时保留可写状态
computer_factory_reset	清除可写状态，并从基础映像重新创建
computer_delete	永久移除计算机

工作原理

┌─────────────┐   MCP   ┌──────────────┐      ┌─────────────────────────┐
│  LLM Agent  │◄───────►│  Sandbox MCP │◄────►│  Sandboxes              │
│  (client)   │         │  MCP Server  │      │  - Docker/Podman        │
│             │         │              │      │  - Cloud VM (Modal,E2B) │
│             │         │              │      │  - WASM Sandbox         │
└─────────────┘         └──────────────┘      └─────────────────────────┘

1. MCP 客户端通过 stdio 启动 MCP Sandbox Computer VM for AI，或通过 HTTP 连接
2. 首次调用 terminal_execute 时，服务会创建一台具名隔离计算机。每个连接都会获得各自的随机默认计算机，除非显式按 ID 连接。
3. 命令在沙箱内运行；返回 stdout、stderr 和退出代码
4. 会话结束时，临时计算机会被销毁；永久计算机则会保留在提供方一侧。

**安全性：**Agent 通过 MCP 与沙箱通信，而不是在沙箱内运行。这是有意为之：Agent 通常需要使用机密信息（API 密钥、系统提示词、代码），而这些信息绝不应暴露在可能遭受提示注入攻击并被窃取的沙箱中。

**Agent 隔离与沙箱生命周期：**未提供 ID 时，每个 MCP 连接都会获得一台隔离的默认计算机。使用显式 ID 表示有意重新连接。Docker 标签和 Fly Machine 元数据使 MCP 服务本身重启后仍可发现永久计算机。

后端示例

所有参数请参阅 CLI 参考。

Docker 和 Podman（默认）

通过 Docker 或 Podman 运行本地容器。任何 OCI 映像均可使用。

uvx mcp-sandbox-computer-vm-for-ai                                # Docker + Debian (defaults)
uvx mcp-sandbox-computer-vm-for-ai --image alpine --engine podman # Podman + Alpine
uvx mcp-sandbox-computer-vm-for-ai --image node:22                # Node.js with networking
uvx mcp-sandbox-computer-vm-for-ai --no-network                   # Disable networking

Docker Compose HTTP 服务

随附映像包含 Docker CLI，并通过其套接字与主机守护进程通信：

docker compose up --build
# Streamable HTTP MCP endpoint: http://127.0.0.1:8080/mcp

如果需要可选的仪表板和 computer_* 工具，请在 Compose 服务环境中设置 ENABLE_LIFECYCLE_TOOLS=true。

compose.yaml 仅绑定到 loopback。若要监听远程连接，请设置 KILNTAINERS_AUTH_TOKEN，并将其作为 Authorization: Bearer … 标头发送。挂载 Docker 套接字会授予该服务控制主机 Docker 守护进程的权限；在生产环境中，请使用专用主机或受限的远程守护进程。

Fly Machines

Fly.io 会将 OCI 镜像部署为 VM 根文件系统。fly 后端通过 flyctl 配置真实的 Fly Machines：临时 Machine 使用可丢弃的根文件系统，永久 Machine 使用 persist_rootfs=always。

常规配置是在本地使用 stdio MCP，连接远程 Fly Machines。无需指定应用、区域、CPU 或内存：

uvx mcp-sandbox-computer-vm-for-ai --backend fly

首次使用时，后端会：

• 使用现有的 fly 或 flyctl，或将当前官方版本下载到 ~/.fly/bin（设置 AUTO_INSTALL_FLYCTL=false 即可选择不自动安装）；
• 使用缓存的 fly auth login 会话、FLY_API_TOKEN 或 FLY_TOKEN；
• 有 personal 组织时选择该组织，否则选择账户中的第一个组织；
• 创建一个自动生成的 Fly App，并将其记录在 ~/.mcp-sandbox-computer-vm-for-ai/fly.json 中；
• 由 Fly 选择区域，默认使用一个共享 CPU 和 512 MB 内存。

身份验证是唯一无法避免的账户步骤。在全新的机器上，先启动一次 MCP 以安装 flyctl，然后运行错误信息中显示的确切 flyctl auth login 命令，再重启 MCP 客户端。CI 可以改为设置 FLY_API_TOKEN。FLY_ORG、FLY_APP_NAME、FLY_REGION 和 --fly-* 标志都是可选的覆盖项。

本仓库的 .mcp.json 已配置为使用 Fly 模式，并会在启用生命周期工具的情况下运行本地检出版本。在检出目录之外使用的客户端，可采用以下等效配置：

{
  "mcpServers": {
    "sandbox-computer-fly": {
      "command": "uvx",
      "args": ["mcp-sandbox-computer-vm-for-ai", "--backend", "fly"],
      "env": {
        "ENABLE_LIFECYCLE_TOOLS": "true",
        "AUTO_INSTALL_FLYCTL": "true"
      }
    }
  }
}

首次调用 terminal_execute 时会创建临时 Machine。若要保留其根文件系统，请传入稳定的 computer_id 并设置 temporary=false（或在控制面板中创建永久计算机）。

托管 MCP 控制器（高级）

附带的 fly.toml 仍可用于托管 MCP HTTP 控制器本身。控制器需要使用应用专属的部署令牌，因为 Fly Machine 无法使用笔记本电脑上缓存的登录凭据：

fly apps create mcp-sandbox-computer-vm-for-ai
fly secrets set -a mcp-sandbox-computer-vm-for-ai \
  FLY_API_TOKEN="$(fly tokens create deploy -a mcp-sandbox-computer-vm-for-ai)" \
  KILNTAINERS_AUTH_TOKEN="$(openssl rand -hex 32)"
fly deploy

远程 MCP 端点为 https://mcp-sandbox-computer-vm-for-ai.fly.dev/mcp；请将 KILNTAINERS_AUTH_TOKEN 作为 bearer 令牌发送。已检入的控制器配置使用 gru，但本地 stdio 模式不会选择区域，除非你明确设置。

云容器和 VM

Modal.com

通过 Modal.com 提供托管容器，启动时间不到一秒。可扩展至数千个并行沙箱。支持 GPU。

uvx mcp-sandbox-computer-vm-for-ai --backend modal
uvx mcp-sandbox-computer-vm-for-ai --backend modal --gpu A10G --region us-east

可通过 modal setup CLI 或 --modal-token-id / --modal-token-secret 标志进行身份验证。

E2B

来自 E2B 的云托管微型 VM 沙箱。

uvx mcp-sandbox-computer-vm-for-ai --backend e2b
uvx mcp-sandbox-computer-vm-for-ai --backend e2b --e2b-api-key ABCD --e2b-template my-custom-alpine

可通过 --e2b-api-key 命令行参数或 E2B_API_KEY 环境变量进行身份验证。

WASM Go BusyBox（实验性）

在 WebAssembly 沙箱中运行 go-busybox。它并非完整的 Linux 环境，但在轻量且安全的沙箱中提供常用工具（grep、awk、sed、ls、wc、sort 等）。

uvx --from "mcp-sandbox-computer-vm-for-ai[wasm]" mcp-sandbox-computer-vm-for-ai --backend go_busybox

WASM Runner

将自定义 WASM 模块作为沙箱后端运行。为 Agent 提供一组编译为 WebAssembly 的工具，以及隔离的文件系统。

uvx --from "mcp-sandbox-computer-vm-for-ai[wasm]" mcp-sandbox-computer-vm-for-ai --backend wasm --wasm-path ./my_tool.wasm

安装

uvx mcp-sandbox-computer-vm-for-ai                    # run without installing
uv tool install mcp-sandbox-computer-vm-for-ai        # recommended
uv tool install mcp-sandbox-computer-vm-for-ai[wasm]  # include WASM backends (+15MB)
pip install mcp-sandbox-computer-vm-for-ai            # also works with pip

需要 Python 3.13+。Docker 后端需要 Docker 或 Podman。Modal 和 E2B 后端需要相应服务的账户。

发布

Node 仅用作跨平台的发布任务运行器；发布的软件包仍为 Python 包。发布命令会同步所有软件包和注册表元数据。

npm run release:check                 # credential-free command self-check
npm run check                         # lint, types, tests, and package build
npm run release -- --dry-run          # full main-branch preflight, no changes
npm run release                       # patch version; GitHub publishes PyPI via OIDC
npm run release -- minor              # minor version release
npm run release -- 1.0.0              # exact version release

PyPI 发布使用 Trusted Publishing，因此本地或 GitHub 中都不会存储 PyPI 令牌。请一次性配置 PyPI 发布者，所有者为 flujo-app，仓库为 mcp-sandbox-computer-vm-for-ai，工作流为 release.yml，环境为 pypi。发布命令会推送版本提交和标签，触发 .github/workflows/release.yml，并等待 PyPI 和 GitHub Release 完成。

PyPI 上显示该版本后，请验证并将其不可变元数据发布到官方 MCP Registry：

npm run registry:validate             # downloads pinned publisher; publishes nothing
npm run registry:release              # GitHub login, then publish server.json

注册表命令会在身份验证前，验证已发布的 PyPI README 所有权标记。保留 mcp:validate 和 mcp:publish 作为别名，以匹配同系列 MCP App 仓库。

CLI 参考

usage: mcp-sandbox-computer-vm-for-ai [-h] [--backend {docker,e2b,fly,go_busybox,modal,wasm}] [--transport {stdio,http}] [...]

MCP server providing isolated Linux sandboxes for LLM agent shell execution.

options:
  -h, --help            show this help message and exit

core options:
  --backend {docker,e2b,fly,go_busybox,modal,wasm}
                        Backend to use (default: docker)
  --transport {stdio,http}
                        MCP transport (default: stdio)
  --host HOST           HTTP bind address (default: 127.0.0.1, HTTP mode only)
  --port PORT           HTTP listen port (default: 8435, HTTP mode only)
  --timeout TIMEOUT     Default exec timeout in seconds (default: 120)
  --output-limit OUTPUT_LIMIT
                        Max combined stdout+stderr bytes per exec (default: 2097152 = 2 MiB)
  --session-timeout SESSION_TIMEOUT
                        Idle session timeout in seconds (default: 300, HTTP mode only)
  --auth-token AUTH_TOKEN
                        Bearer token for /mcp (default: KILNTAINERS_AUTH_TOKEN)
  --allow-unauthenticated-http
                        Explicitly allow a non-loopback listener without built-in auth
  --shell SHELL         Shell binary for command mode (e.g., /bin/bash, ash). Default: /bin/bash.
  --network, --no-network
                        Enable network access in sandboxes (default: enabled)

tool description:
  --tool-instruction-override TOOL_INSTRUCTION_OVERRIDE
                        Replace the entire terminal_execute tool description
  --extended-tool-instruction EXTENDED_TOOL_INSTRUCTION
                        Append to the backend's default tool description

docker backend options:
  --engine ENGINE       Container CLI binary (default: docker). Supports podman.
  --docker-host DOCKER_HOST
                        Docker daemon socket/address, passed as -H to the Docker CLI (e.g., "ssh://user@remote-host", "tcp://host:2375")
  --image IMAGE         Docker image (default: debian:bookworm-slim)
  --cpu CPU             Docker CPU limit (e.g., "1.5")
  --memory MEMORY       Docker memory limit (e.g., "512m")
  --docker-run-flag DOCKER_RUN_FLAGS
                        Additional flag passed to docker run. Repeatable. (e.g., --docker-run-flag "--pids-limit=256")

fly backend options:
  --fly-cli FLY_CLI     flyctl/fly executable (default: fly)
  --fly-app FLY_APP     Fly App that owns sandbox Machines (default: FLY_APP_NAME)
  --fly-token FLY_TOKEN Fly API token (default: FLY_API_TOKEN or FLY_TOKEN)
  --fly-image FLY_IMAGE Base OCI image for sandbox Machines
  --fly-region FLY_REGION
                        Region for newly created Machines
  --fly-cpu-kind {shared,performance}
  --fly-cpus FLY_CPUS
  --fly-memory FLY_MEMORY
                        Memory per Machine in MB
  --fly-rootfs-size FLY_ROOTFS_SIZE
                        Optional root filesystem size in GB

e2b backend options:
  --e2b-api-key E2B_API_KEY
                        E2B API key (overrides E2B_API_KEY environment variable)
  --e2b-template E2B_TEMPLATE
                        E2B template name or ID (default: base)
  --e2b-sandbox-timeout E2B_SANDBOX_TIMEOUT
                        Sandbox lifetime timeout in seconds (default: 3600)
  --e2b-metadata E2B_METADATA
                        Metadata key=value pairs (can be used multiple times)
  --e2b-env E2B_ENV     Environment variable key=value pairs (can be used multiple times)

modal backend options:
  --modal-token-id MODAL_TOKEN_ID
                        Modal token ID (overrides environment/default auth)
  --modal-token-secret MODAL_TOKEN_SECRET
                        Modal token secret (overrides environment/default auth)
  --modal-app-name MODAL_APP_NAME
                        Modal app name
  --modal-cpu MODAL_CPU
                        CPU cores (fractional, default: 1.0)
  --modal-memory MODAL_MEMORY
                        Memory in MiB (default: 512)
  --gpu GPU             GPU type (e.g., "A10G", "H100")
  --region REGION       Geographic region (e.g., "us-east")
  --sandbox-timeout SANDBOX_TIMEOUT
                        Sandbox lifetime timeout in seconds (default: 3600, max 86400)

wasm backend options:
  --wasm-path WASM_PATH
                        Path to the .wasm file to execute (required for wasm backend)
  --wasm-max-memory WASM_MAX_MEMORY
                        Max WASM memory in MiB (default: 256)
  --wasm-fuel WASM_FUEL
                        WASM instruction fuel limit (default: unlimited)