agentbox

Self-hosted code execution sandbox for AI agents — one docker compose up gives you an HTTP API for running untrusted code in isolated environments.

Status: v0.6 — Python + Node subprocess sandbox, timeouts, memory limits, Linux default-deny egress (unshare/bwrap) with network_isolated, TypeScript client, workspace snapshots.

60-second try

pip install agentbox-sandbox
agentbox serve   # API on :8080
# or: docker compose up agentbox
curl -s http://localhost:8080/health
curl -s -X POST http://localhost:8080/v1/run \
  -H 'Content-Type: application/json' \
  -d '{"code":"print(sum(range(10)))"}'

Why this vs alternatives

Problem

Every agent that writes and runs code needs a safe execution environment. Teams either YOLO in shared containers or pay per-second for hosted sandboxes. Self-hosting gVisor/Firecracker is weeks of work.

Key features (v0.6)

• HTTP API: POST /v1/run executes Python or JavaScript
• Per-request limits.timeout_seconds (HTTP 408 on timeout)
• Per-request limits.memory_mb (sets RLIMIT_AS; 16–8192); response includes limits_applied + oom_killed
• AGENTBOX_MAX_MEMORY_MB clamps requested memory
• Default-deny egress when possible: Linux wraps with unshare --net or bwrap --unshare-net; response includes network_isolated
• Workspace snapshots: "snapshot": true then "snapshot_id"
• Python SDK + TypeScript client (sdk/ts/client.ts)
• Docker image includes Node.js for the JS runtime
• Credential stripping when the backend is not unrestricted (macOS stays scrub-only)

Architecture

Agent / SDK
    └── POST /v1/run
            └── SubprocessSandbox (MVP)
                    └── (next) gVisor / Docker backend

Installation

pip install agentbox-sandbox
pip install -e ".[dev]"

Usage

Start server

agentbox serve
# or
docker compose up agentbox

Run code

curl -X POST http://localhost:8080/v1/run \
  -H 'Content-Type: application/json' \
  -d '{"code": "print(sum(range(10)))"}'

curl -X POST http://localhost:8080/v1/run \
  -H 'Content-Type: application/json' \
  -d '{"code": "x = bytearray(10**9)", "limits": {"memory_mb": 64, "timeout_seconds": 5}}'

Python SDK

from agentbox.sdk.client import AgentboxClient

client = AgentboxClient("http://localhost:8080")
print(client.health())
print(client.run("print('hello')"))
print(client.run("console.log('hello')", language="javascript", timeout_seconds=5))
print(client.run("x = bytearray(10**8)", memory_mb=64))
snap = client.run("open('memo.txt','w').write('kept')", snapshot=True)
print(client.run("print(open('memo.txt').read())", snapshot_id=snap["snapshot_id"]))
client.close()

Docker

docker compose up agentbox        # start API on :8080
docker compose run --rm test    # run unit tests

Configuration

Running tests

pytest tests/ -v

Roadmap

• Node.js runtime + TypeScript client + per-run timeout
• Filesystem snapshot/restore (tar workspaces)
• limits.memory_mb via RLIMIT_AS
• Default-deny egress via Linux netns (unshare/bwrap) when available
• gVisor runsc backend with warm pool
• Egress allowlists (beyond all-or-nothing netns)

License

MIT

Known limitations (v0.6)

• Subprocess sandbox only — not production-grade isolation
• RLIMIT_AS is a soft address-space cap, not a cgroup memory controller
• Default-deny egress uses Linux unshare/bwrap when present; macOS stays credential-scrub only (network_isolated: false)
• Single-node, no warm pool
• TypeScript client is source-only (not published to npm)