Tiny Agent Sandbox

A small, inspectable Docker-backed sandbox that agents can call as an MCP tool.

It runs Python, JavaScript, or shell snippets in a new container with no network, no host mounts, a read-only root filesystem, a non-root user, dropped capabilities, and hard resource/output limits. Results are returned as structured data for an agent to reason about.

What the agent sees

The MCP server exposes two tools:

• sandbox_status() reports Docker readiness and missing runtime images.

• run_code(language, code, timeout_seconds) returns stdout, stderr, exit status, timeout and truncation flags, duration, and the runtime image.

The agent cannot choose an image, command, mount, environment variable, network policy, or Docker flag. Those remain operator-controlled policy.

Related MCP server: Sandbox Agent

Quick start

Prerequisites: Docker, Python 3.11+, and uv.

git clone https://github.com/wesleyzhangwq/tiny-agent-sandbox.git
cd tiny-agent-sandbox

docker pull python:3.12-alpine
docker pull node:22-alpine
docker pull alpine:3.22

uv sync --no-editable
uv run --no-editable tas doctor
uv run --no-editable tas run python -c 'print(sum(range(10)))'

Start the MCP server over stdio:

uv run --no-editable tiny-agent-sandbox

Connect an MCP client

For clients that accept the common mcpServers JSON shape:

{
  "mcpServers": {
    "tiny-agent-sandbox": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wesleyzhangwq/tiny-agent-sandbox",
        "tiny-agent-sandbox"
      ]
    }
  }
}

Pull the three runtime images before starting the client. Tool calls use --pull=never, so an agent cannot cause an image download.

Example tool input:

{
  "language": "python",
  "code": "import statistics\nprint(statistics.mean([2, 4, 9]))",
  "timeout_seconds": 5
}

Example structured result:

{
  "language": "python",
  "image": "python:3.12-alpine",
  "exit_code": 0,
  "stdout": "5\n",
  "stderr": "",
  "timed_out": false,
  "output_truncated": false,
  "duration_ms": 180
}

Default policy

The fixed policy is assembled in src/tiny_agent_sandbox/runner.py. Timeout and output overflow remove the named container rather than merely terminating the Docker client.

Development

uv sync --no-editable --extra dev
uv run --no-editable ruff check .
uv run --no-editable pytest -m "not integration"

docker pull python:3.12-alpine node:22-alpine alpine:3.22
uv run --no-editable pytest -m integration

The preliminary ecosystem notes and design tradeoffs are in docs/research.md.

Roadmap

• Optional gVisor (runsc) backend with explicit runtime detection.

• Digest-pinned, operator-configurable runtime images.

• Per-session workspaces with strict size and lifetime limits.

• Egress proxy with destination allowlists and audit logs.

• Concurrency quotas and OpenTelemetry execution traces.

License

Apache-2.0