Sandbox Compute Broker

Sandbox Compute Broker lets an AI agent run compute tasks in a secure sandbox and see the results as an interactive UI — brokering every exchange so the interface and the execution environment stay safely isolated from each other.

The broker is free and open source (Apache-2.0). Your costs are hardware and ops, not API bills — there are no cloud accounts or API keys in the default path.

---

What it does

When an agent needs to do something computational (analyse a CSV, generate a report, run a script), it calls one of the broker's tools. The broker:

1. Runs the request in a sandbox — an isolated environment for untrusted code.
2. Reuses the session — follow-up calls hit the same sandbox so loaded datasets stay loaded.
3. Handles files — /workspace is private scratch; /outputs is surfaced only when the agent explicitly calls present_output.
4. Renders a UI when it helps — via MCP Apps, so results appear as an interactive dashboard instead of a wall of text. UI is optional.

agent → host → broker (OURS) → sandbox
                  ↑ owns both sandbox connection + ui:// resource

---

Prerequisites

Provider	What you need	Isolation
microsandbox (default)	KVM on Linux · Apple Silicon on macOS · WHP on Windows	microVM (libkrun)
Docker (fallback)	Docker Engine running; docker build -t mcp-sandbox:latest sandbox-image/	OCI container (+gVisor if runsc installed)
Local	Nothing	subprocess — test scaffolding only, not a security boundary

The broker auto-selects: tries microsandbox first, falls back to Docker, bails with an actionable error if neither is available. Override with BROKER_PROVIDER=microsandbox|docker|local.

---

Quickstart (under 15 minutes)

# 1. Clone + install
git clone https://github.com/your-org/sandbox-compute-broker
cd sandbox-compute-broker
npm install

# 2a. If using microsandbox (default — needs virtualization support):
#     No extra steps; the SDK spawns microVMs as child processes.

# 2b. If using Docker (fallback):
docker build -t mcp-sandbox:latest sandbox-image/

# 3. Verify everything works
npx tsc -p tsconfig.json --noEmit        # type-check
npx vitest run                           # unit tests (59 pass, no daemon needed)

# 4. Run the dashboard server
BROKER_PROVIDER=local npm run dev        # local subprocess, for rapid iteration
# or:
npm run dashboard                        # auto-selects best available provider

Add to Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "sandbox-compute-broker": {
      "command": "npx",
      "args": ["tsx", "examples/dashboard/server.ts"]
    }
  }
}

Then restart Claude Desktop and ask it to call the data_dashboard tool.

---

Tools exposed

Tool	UI?	What it does
run_code	No	Run code in the session sandbox; return stdout/stderr/exitCode.
run_command	No	Run an arbitrary command in the session sandbox.
present_output	No	Promote a /workspace file to /outputs; return resource:// URI.
data_dashboard	Yes	Run an analysis step + render an interactive App. Callbacks reuse the same sandbox.

Output resources are read via resources/read — bytes never base64-inlined into a tool result.

---

Provider swap

BROKER_PROVIDER=docker npx tsx examples/dashboard/server.ts
BROKER_PROVIDER=microsandbox npx tsx examples/dashboard/server.ts

Zero App or tool changes required — the SandboxProvider interface is the portability contract (see SPEC.md).

---

Project layout

src/
  providers/
    base.ts          SandboxProvider interface + types (SPEC §1)
    local.ts         LocalSandboxProvider — subprocess, test scaffolding only
    microsandbox.ts  MicrosandboxProvider — microVM via libkrun (primary)
    docker.ts        DockerSandboxProvider — OCI container + gVisor (fallback)
    index.ts         selectProvider() + forceFromEnv()
  session.ts         SessionManager — reuse, TTL, idle reap, caps, reconnect
  store.ts           SessionStore interface — InMemorySessionStore + Redis stub
  files.ts           FileLifecycle — workspace/outputs, resource:// refs
  policy.ts          Policy — allow-list, egress, secrets, audit log
  broker.ts          MCP server — tool + ui:// registration
ui/analytics-dashboard/
  app.ts             In-iframe App (calls data_dashboard back)
  shell.html         HTML shell
  build.ts           esbuild bundler (produces single inline <script>)
sandbox-image/
  Dockerfile         Pinned OCI image (python + analysis libs)
examples/
  phase0-spike/      Session-identity spike (see SPEC.md §3)
  dashboard/         Phase 2 flagship: data dashboard over stdio
tests/
  *.test.ts          59 tests — providers, session, files, policy, broker, limits
SPEC.md              Frozen v0 provider interface + file-lifecycle contract
PLAN.md              Design doc (v5)
STATUS.md            Phase-by-phase implementation status

---

Architecture

The four layers (PLAN.md §7):

[1] MCP App (iframe)           ← @modelcontextprotocol/ext-apps    (optional)
        ↕ postMessage / JSON-RPC
    Host (Claude Desktop, …)
        ↕ MCP transport (stdio / streamable HTTP)
[2] MCP Broker                 ← src/broker.ts                      (OURS)
[3] Core                       ← session · files · policy           (OURS)
        ↕ provider SDK
[4] Sandbox                    ← microsandbox microVM / Docker OCI

The App can never reach the sandbox directly (iframe isolation). Every byte flows through the broker.

---

Security model

• Isolation level is declared by capabilities().isolationLevel so the deployer always knows what boundary they have (subprocess | container | container+gvisor | microvm).
• /workspace is never auto-exposed. The only path to the user is present_output.
• Egress is blocked by default (disableNetwork() / --network=none). The Policy layer manages an allow-list.
• Secrets are injected at call time; never baked into images, code, or logs. The Policy layer redacts any configured secret values from stdout/stderr before they reach the audit log or the host.
• Audit log: one JSON line per execution ({ts, tool, provider, isolationLevel, sandboxId, exitCode, durationMs, bytesOut, policyDecisions[]}), OWASP agentic-risk mapped.

See docs/threat-model.md for the full per-edge-case analysis.

---

Overlap with microsandbox-mcp

microsandbox-mcp is microsandbox's own compute-only MCP server. Ours is different:

• MCP Apps UI loop (interactive dashboards with App-iframe callbacks).
• Provider portability: swap microsandbox ↔ Docker with one env var; the SPEC.md interface lets you write third-party adapters.
• FileLifecycle (explicit output promotion, resource:// refs, no base64 in tool results).
• Governance: per-tool allow-list, egress control, secret redaction, OWASP-mapped audit log.

---

License

Apache-2.0. AGPL adapters (Daytona) are isolated in separate packages.

SandboxCompute