Sandbox

LLM-first sandboxing for agents.

This repository defines a small semantic MCP surface over isolated Docker runtimes and ships itself as an Agent Plugin. The public contract is designed for models first: eight tools, progressive capability disclosure, a single /workspace, and explicit sandbox lifecycle.

Principles

• LLM semantics over REST completeness. Models see task-oriented tools, not every low-level runtime endpoint.

• Progressive disclosure. sandbox_discover reveals details only when an agent needs them.

• One workspace. Shell, files, browser downloads, generated artifacts, and future tools share /workspace.

• Runtime independence. MCP semantics do not depend on Docker. Docker is the first runtime adapter.

• Explicit lifecycle. Sandboxes are created, inspected, used, and destroyed deliberately.

• Artifacts are first-class. Files produced in /workspace can be enumerated and returned without leaking host details.

• Defense in depth. The runtime is container-isolated, capability-dropped, resource-limited, and never receives the Docker socket.

• Observable work. Every sandbox has a noVNC desktop and code-server; the headed Chromium shown on the desktop is the same browser controlled by sandbox_browser.

Related MCP server: mcp-agent-tools

Tool contract

The MCP server exposes exactly eight tools in v0.2:

Human-facing desktop/VS Code access is returned as metadata by sandbox_create and sandbox_inspect; it does not add model tools.

Architecture

Agent / Client
     |
     | Agent Plugins v1 + MCP
     v
+-----------------------------+
| Sandbox MCP                 |
| 8 semantic tools            |
| progressive disclosure      |
+-------------+---------------+
              |
              | Runtime interface
              v
+-----------------------------+
| DockerRuntime               |
| lifecycle + daemon client   |
+-------------+---------------+
              |
              | localhost-only mapped port
              v
+-----------------------------+
| Sandbox runtime container   |
| daemon                      |
| shell + filesystem          |
| headed Chromium / Playwright|
| Xvfb + Openbox + noVNC      |
| code-server                 |
| /workspace                  |
+-----------------------------+

The container daemon is intentionally not the model-facing API. It is an internal runtime protocol. Future adapters can implement the same runtime interface using Kubernetes, Firecracker, cloud sandboxes, or another isolation backend without changing the MCP tool contract.

Requirements

• Node.js 24+

• pnpm 12+

• Docker Engine / Docker Desktop

Development

corepack enable
pnpm install
pnpm check
pnpm image:build
pnpm dev:mcp

The MCP server uses PLUGIN_DATA when launched as an Agent Plugin. During local development it defaults to .sandbox-data.

Build the runtime image

pnpm image:build

This creates both local tags:

ghcr.io/nagaozen/sandbox-runtime:latest
nagaozen/sandbox-runtime:dev

Override the image selected by the MCP server with:

SANDBOX_IMAGE=my-registry/sandbox-runtime:tag

Human desktop and VS Code

Every created sandbox returns two loopback-only interfaces:

• interfaces.desktop.url — noVNC desktop showing the headed Chromium session the LLM is controlling.

• interfaces.vscode.url — code-server opened directly on /workspace.

This intentionally preserves the useful observability of the older AIO container without increasing the LLM tool catalog. For a server-hosted chat interface, proxy interfaces.desktop.hostPort and interfaces.vscode.hostPort through authenticated application routes with WebSocket support. See docs/interfaces.md.

Agent Plugin

The repository root is an Agent Plugins v1 package:

plugin.json
mcp.json
skills/

Build the distributable plugin:

pnpm plugin:package

This creates release/plugin/ with the standard plugin.json, mcp.json, Skill, license, and a single bundled bin/sandbox.mjs. A compatible client can install that directory and launch the MCP server over stdio.

The plugin requires Node.js 24+ and Docker on the client host, but it does not require pnpm, a source checkout, or node_modules. The MCP process manages sandbox containers through the host Docker CLI.

Agent Plugins deliberately leaves installation and credential handling to clients. This plugin therefore does not embed secrets.

Example agent flow

sandbox_discover()
sandbox_create()
sandbox_exec("git clone ...")
sandbox_files(read package.json)
sandbox_exec("pnpm test")
sandbox_browser(navigate http://...)
sandbox_artifacts(list)
sandbox_destroy()

Agents should normally create one sandbox per task and reuse it until the task is complete.

Security model

The sandbox container is untrusted execution space.

The Docker adapter:

• drops Linux capabilities,

• enables no-new-privileges,

• enforces CPU, memory, PID, and shared-memory limits,

• binds the internal daemon only to 127.0.0.1 on a random host port,

• does not mount the Docker socket into the sandbox,

• mounts only the task workspace,

• supports disabling network access.

Commands can do anything allowed inside the container. They cannot be treated as a policy boundary by themselves.

See docs/security.md.

Repository layout

apps/
  mcp/                 model-facing MCP server
  daemon/              internal runtime daemon
packages/
  protocol/            shared schemas and semantic types
  runtime/             runtime abstraction
  client/              daemon client
  runtime-docker/      Docker adapter
skills/
  sandbox/             Agent Skill
image/
  Dockerfile
docs/
tests/

Status

0.2.0 is intentionally small. The architecture is meant to stabilize before adding more tool surface.

License

Apache-2.0.