mirror of
https://github.com/yashshah9/agentbox.git
synced 2026-11-18 18:03:44 +00:00
1c3c07df1df65dce6d48b57ef4e3c553ec773aa2
Context: - When deny_egress is on, probe unshare/bwrap and wrap runs in a netns; report network_isolated. - Falls back to credential scrub when privileges are missing. Test Plan: - docker compose run --rm test pytest tests/ -q Additional Notes: - Version 0.6.0.
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) withnetwork_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
| Approach | Strength | Gap |
|---|---|---|
| agentbox | Self-hosted HTTP API + SDK, one compose file | Subprocess isolation today, not gVisor |
| Hosted sandboxes (E2B, etc.) | Strong isolation, managed | Per-second cost; data leaves your network |
Raw docker exec |
Familiar | No agent-oriented API / snapshots / limits |
| YOLO in the agent process | Zero infra | Full host compromise risk |
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/runexecutes Python or JavaScript - Per-request
limits.timeout_seconds(HTTP 408 on timeout) - Per-request
limits.memory_mb(setsRLIMIT_AS; 16–8192); response includeslimits_applied+oom_killed AGENTBOX_MAX_MEMORY_MBclamps requested memory- Default-deny egress when possible: Linux wraps with
unshare --netorbwrap --unshare-net; response includesnetwork_isolated - Workspace snapshots:
"snapshot": truethen"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
| Component | Technology | Why |
|---|---|---|
| API | FastAPI | Async-ready, OpenAPI docs, widely adopted |
| Server | uvicorn | Standard ASGI server |
| Config | pydantic-settings | Typed env config |
| Tests | pytest + httpx TestClient | Fast API testing |
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
| Variable | Default | Description |
|---|---|---|
AGENTBOX_HOST |
0.0.0.0 |
Bind host |
AGENTBOX_PORT |
8080 |
Bind port |
AGENTBOX_DEFAULT_TIMEOUT_SECONDS |
30 |
Execution timeout |
AGENTBOX_DEFAULT_MEMORY_MB |
unset | Optional default RLIMIT_AS cap |
AGENTBOX_MAX_MEMORY_MB |
unset | Clamp requested memory_mb to this max |
AGENTBOX_SANDBOX_BACKEND |
subprocess |
Backend selector |
AGENTBOX_SNAPSHOT_DIR |
/tmp/agentbox-snapshots |
Workspace snapshot store |
Running tests
pytest tests/ -v
Roadmap
- Node.js runtime + TypeScript client + per-run timeout
- Filesystem snapshot/restore (tar workspaces)
limits.memory_mbviaRLIMIT_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_ASis a soft address-space cap, not a cgroup memory controller- Default-deny egress uses Linux
unshare/bwrapwhen present; macOS stays credential-scrub only (network_isolated: false) - Single-node, no warm pool
- TypeScript client is source-only (not published to npm)
Languages
Python
95.9%
TypeScript
2.6%
Dockerfile
1.5%