MCP Sandbox Computer VM for AI

Named, manageable Linux computers for AI agents — via MCP

MCP Sandbox Computer VM for AI is a lifecycle-focused fork of Kilntainers. It gives agents isolated Linux computers, stable IDs, temporary or persistent lifecycles, an interactive MCP App dashboard, and first-class Docker and Fly Machines backends.

• 🖥️ MCP App dashboard: List computers, run commands, restart, factory reset, and delete from FLUJO or another stable MCP Apps host.
• 🏷️ Named computers: Reconnect with a stable computer_id, or omit it to receive a readable random slug.
• 💾 Explicit lifecycle: Temporary computers are removed with their MCP session; permanent computers survive and can be reattached later.
• 🧰 Multiple backends: Docker/Podman, native Fly Machines, Modal, E2B, and WebAssembly.
• 🏝️ Isolated per agent: Every agent gets its own dedicated sandbox — no shared state, no cross-contamination.
• 🔒 Secure by design: The agent communicates with the sandbox over MCP — it doesn’t run inside it. No agent API keys, code, or prompts are exposed to the sandbox.
• 🔌 Tool and UI access: terminal_execute stays simple, while optional provider-neutral lifecycle tools power both models and the dashboard.
• 📈 Scalable: Scale from a few agents on your laptop to thousands running in parallel in the cloud.

Why sandbox computers?

Agents are already excellent at using terminals and can save thousands of tokens with common Linux utilities like grep, find, jq, and awk. Giving an agent access to the host OS is dangerous, while provisioning large numbers of isolated environments is operationally painful. MCP Sandbox Computer VM for AI gives every agent a dedicated sandbox with an explicit lifecycle.

Quick Start

Run the released package directly from PyPI. Docker and stdio are the defaults:

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

Add it to Claude Code:

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

Or add it to a JSON-based MCP client such as Claude Desktop:

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

By default, the server exposes only terminal_execute. Set ENABLE_LIFECYCLE_TOOLS=true before starting the server to expose the computer_* tools and MCP App dashboard. For a JSON-based stdio client, add it to the server configuration:

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

Then call computer_dashboard to open the App. The dashboard has no external browser dependencies. Its internal resource URI remains ui://kilntainers/computers for compatibility with the upstream implementation.

Named computer lifecycle

terminal_execute accepts two additional optional inputs:

• computer_id: a 1–63 character lowercase slug. The first call without one creates a readable random ID and reuses it as that MCP session's default.
• temporary: defaults to true. Temporary computers are removed when the owning MCP session closes. Set it to false for a computer that survives server/session shutdown and can be reattached later by ID.

Every execution result includes computer_id and temporary next to stdout, stderr, exit code, and duration:

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

Lifecycle tools are provider-neutral and are disabled unless ENABLE_LIFECYCLE_TOOLS=true:

How It Works

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

1. An MCP client starts MCP Sandbox Computer VM for AI over stdio or connects over HTTP
2. On the first terminal_execute call, the server creates a named isolated computer. Each connection gets its own random default unless it explicitly attaches by ID.
3. Commands run inside the sandbox; stdout, stderr, and exit code are returned
4. When the session ends, temporary computers are destroyed; permanent computers remain provider-side.

Security: The agent communicates with the sandbox over MCP — it doesn't run inside it. This is intentional: agents often need secrets (API keys, system prompts, code), and those should never be exposed inside a sandbox where a prompt injection could exfiltrate them.

Agent Isolation & Sandbox Lifecycle: An omitted ID gives each MCP connection an isolated default computer. Explicit IDs make reconnection intentional. Docker labels and Fly Machine metadata make permanent computers discoverable after the MCP server itself restarts.

Backend Examples

See the CLI Reference for all arguments.

Docker and Podman (default)

Local containers via Docker or Podman. Any OCI image works.

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 server

The included image contains the Docker CLI and talks to the host daemon through its socket:

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

Set ENABLE_LIFECYCLE_TOOLS=true in the Compose service environment when you want the optional dashboard and computer_* tools.

compose.yaml binds only to loopback. For a remote listener, set KILNTAINERS_AUTH_TOKEN and send it as an Authorization: Bearer … header. Mounting the Docker socket grants the service control of the host Docker daemon; use a dedicated host or a restricted remote daemon in production.

Fly Machines

Fly.io deploys OCI images as VM root filesystems. The fly backend provisions real Fly Machines through flyctl: temporary Machines use disposable root filesystems, while permanent Machines use persist_rootfs=always.

The normal setup is local stdio MCP with remote Fly Machines. There are no required app, region, CPU, or memory choices:

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

On first use the backend:

• uses an existing fly or flyctl, or downloads the current official release to ~/.fly/bin (set AUTO_INSTALL_FLYCTL=false to opt out);
• uses your cached fly auth login session, FLY_API_TOKEN, or FLY_TOKEN;
• chooses the personal organization when available, otherwise the first organization on the account;
• creates a generated Fly App once and remembers it in ~/.mcp-sandbox-computer-vm-for-ai/fly.json;
• lets Fly choose the region and uses one shared CPU with 512 MB by default.

Authentication is the only unavoidable account step. On a genuinely fresh machine, start the MCP once so it installs flyctl, then run the exact flyctl auth login command shown by its error and restart the MCP client. CI can set FLY_API_TOKEN instead. FLY_ORG, FLY_APP_NAME, FLY_REGION, and the --fly-* flags remain optional overrides.

This repository's .mcp.json is ready for Fly mode and runs the local checkout with lifecycle tools enabled. For a client outside the checkout, use this equivalent configuration:

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

The first terminal_execute call creates a temporary Machine. To keep its root filesystem, pass a stable computer_id and temporary=false (or create a permanent computer in the dashboard).

Hosted MCP controller (advanced)

The included fly.toml can still host the MCP HTTP controller itself. This requires an app-scoped deploy token inside that controller because a Fly Machine cannot use your laptop's cached login:

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