MCP Sandbox Computer VM for AI

AI 向け MCP Sandbox Computer VM

AI エージェント向けの、名前を付けて管理できる Linux コンピューター — MCP 経由

MCP Sandbox Computer VM for AI は、Kilntainers をライフサイクル管理に特化させたフォークです。エージェントに、分離された Linux コンピューター、安定した ID、一時的または永続的なライフサイクル、インタラクティブな MCP App ダッシュボード、そして Docker と Fly Machines の第一級のバックエンドを提供します。

• 🖥️ MCP App ダッシュボード： FLUJO やその他の安定した MCP Apps ホストから、コンピューターの一覧表示、コマンドの実行、再起動、工場出荷時設定へのリセット、削除ができます。
• 🏷️ 名前付きコンピューター： 安定した computer_id を使って再接続するか、省略して読みやすいランダムなスラッグを受け取れます。
• 💾 明示的なライフサイクル： 一時的なコンピューターは MCP セッション終了時に削除されます。永続的なコンピューターは保持され、後で再接続できます。
• 🧰 複数のバックエンド： Docker／Podman、ネイティブ Fly Machines、Modal、E2B、WebAssembly。
• 🏝️ エージェントごとに分離： 各エージェントに専用のサンドボックスを用意するため、状態の共有や相互干渉はありません。
• 🔒 設計段階から安全： エージェントは MCP 経由でサンドボックスと通信します。サンドボックス内で実行されるわけではありません。エージェントの API キー、コード、プロンプトがサンドボックスに公開されることはありません。
• 🔌 ツールと UI へのアクセス： terminal_execute はシンプルなまま、オプションのプロバイダー中立なライフサイクルツールがモデルとダッシュボードの両方を支えます。
• 📈 スケーラブル： ノート PC で数個のエージェントを動かすところから、クラウドで数千のエージェントを並行稼働させるところまで拡張できます。

サンドボックスコンピューターを使う理由

エージェントはすでにターミナルの操作に優れており、grep、find、jq、awk などの一般的な Linux ユーティリティを使うことで、トークンを数千個節約できます。エージェントにホスト OS へのアクセスを許可するのは危険です。一方、分離された環境を大量にプロビジョニングするのは運用上の負担になります。MCP Sandbox Computer VM for AI は、各エージェントに明示的なライフサイクルを持つ専用サンドボックスを提供します。

クイックスタート

リリース済みのパッケージを 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 は、次の2つの追加オプション入力を受け付けます。

• computer_id：1〜63文字の小文字のスラッグです。指定せずに最初の呼び出しを行うと、読みやすいランダムな ID が作成され、その MCP セッションのデフォルトとして再利用されます。
• temporary：デフォルトは true です。一時コンピューターは、所有する MCP セッションが終了すると削除されます。サーバー／セッションのシャットダウン後も存続し、後から ID で再接続できるコンピューターにするには、false に設定してください。

各実行結果には、標準出力、標準エラー、終了コード、実行時間とともに、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 を指定して作成／接続する。省略した場合は必ず新しいスラッグを生成する
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 クライアントが MCP Sandbox Computer VM for AI を stdio 経由で起動するか、HTTP 経由で接続します
2. 最初の terminal_execute 呼び出し時に、サーバーが名前付きの分離されたコンピューターを作成します。ID を明示的に指定して接続しない限り、接続ごとに独自のランダムなデフォルトが割り当てられます。
3. コマンドはサンドボックス内で実行され、標準出力、標準エラー、終了コードが返されます
4. セッション終了時に、一時コンピューターは破棄され、永続コンピューターはプロバイダー側に残ります。

セキュリティ： エージェントは MCP 経由でサンドボックスと通信します。サンドボックス内で実行されるわけではありません。これは意図的な設計です。エージェントは API キー、システムプロンプト、コードなどのシークレットを必要とすることが多く、プロンプトインジェクションで持ち出される可能性のあるサンドボックス内に、それらを決して公開すべきではありません。

エージェントの分離とサンドボックスのライフサイクル： 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 はループバックインターフェイスのみにバインドします。リモートから接続できるようにするには、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 1 基と 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 からは、ノート PC にキャッシュされたログインを使用できないためです：

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 をベアラートークンとして送信してください。チェックイン済みのコントローラー設定では gru を使用しますが、ローカルの stdio モードでは、明示的に設定しない限りリージョンは選択されません。

クラウドコンテナーと VM

Modal.com

Modal.com による、1 秒未満で起動するホスト型コンテナーです。数千のサンドボックスに並列でスケールできます。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 CLI 引数、または 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 モジュールをサンドボックスのバックエンドとして実行します。エージェントに 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を使用するため、PyPI トークンをローカルにも GitHub にも保存しません。PyPI の発行元として、owner に flujo-app、repository に mcp-sandbox-computer-vm-for-ai、workflow に release.yml、environment に 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)