Files
Yash Shah d1c349e59f feat(v0.8): egress allowlists for sandboxed runs
Support AGENTBOX_EGRESS_ALLOWLIST and per-request egress_allowlist.
Empty list keeps deny-all (Docker --network=none / Linux netns); a
non-empty list applies a soft Python/Node userspace filter and returns
the effective hosts on the run response.
2026-09-18 21:06:01 +05:30

195 lines
7.6 KiB
Markdown

# 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.
[![PyPI](https://img.shields.io/pypi/v/agentbox-sandbox.svg)](https://pypi.org/project/agentbox-sandbox/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![CI](https://github.com/yashshah9/agentbox/actions/workflows/ci.yml/badge.svg)](https://github.com/yashshah9/agentbox/actions/workflows/ci.yml)
> **Status:** v0.8 — Docker/subprocess sandboxes, **egress allowlists**, timeouts, memory limits, snapshots, TypeScript client.
## 60-second try
```bash
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; Docker or subprocess backends | Not gVisor/Firecracker (yet) |
| 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.8)
- HTTP API: `POST /v1/run` executes Python or JavaScript
- **Docker backend** (`AGENTBOX_SANDBOX_BACKEND=docker`): ephemeral `docker run --rm`, `--network=none`, optional `--memory`, workspace at `/work`
- Subprocess backend remains the **default** for easy local tests
- Per-request `limits.timeout_seconds` (HTTP 408 on timeout)
- Per-request `limits.memory_mb` (Docker `--memory` or subprocess `RLIMIT_AS`); response includes `limits_applied` + `oom_killed`
- `AGENTBOX_MAX_MEMORY_MB` clamps requested memory
- Default-deny egress: Docker `--network=none` / Linux `unshare`/`bwrap` (`network_isolated`)
- **Egress allowlists**: `AGENTBOX_EGRESS_ALLOWLIST` + per-request `egress_allowlist` (soft userspace filter when non-empty)
- Workspace snapshots: `"snapshot": true` then `"snapshot_id"`
- Python SDK + TypeScript client (`sdk/ts/client.ts`)
- Credential stripping when the backend is not `unrestricted`
## Architecture
```
Agent / SDK
└── POST /v1/run
├── SubprocessSandbox (default — easy tests)
└── DockerSandbox (recommended — stronger isolation)
```
| Component | Technology | Why |
|-----------|------------|-----|
| API | FastAPI | Async-ready, OpenAPI docs, widely adopted |
| Server | uvicorn | Standard ASGI server |
| Config | pydantic-settings | Typed env config |
| Isolation | Docker / subprocess | Docker for production; subprocess for CI/dev |
| Tests | pytest + httpx TestClient | Fast API testing |
## Installation
```bash
pip install agentbox-sandbox
pip install -e ".[dev]"
```
## Usage
### Start server
```bash
agentbox serve
# or
docker compose up agentbox
```
### Recommended: Docker sandbox backend
Requires the Docker CLI (and a reachable daemon) on the host running agentbox:
```bash
export AGENTBOX_SANDBOX_BACKEND=docker
# optional:
# export AGENTBOX_DOCKER_IMAGE=python:3.12-slim
# export AGENTBOX_DOCKER_NODE_IMAGE=node:20-slim
agentbox serve
```
Each `/v1/run` starts an ephemeral container, mounts a temp workspace at `/work`, applies timeout on `docker run`, and removes the container (`--rm`). Health and run responses report `backend: "docker"`.
### Run code
```bash
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}}'
# Allowlisted egress (subset of AGENTBOX_EGRESS_ALLOWLIST when set):
curl -X POST http://localhost:8080/v1/run \
-H 'Content-Type: application/json' \
-d '{"code":"print(1)","egress_allowlist":["example.com"]}'
```
### Python SDK
```python
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
```bash
docker compose up agentbox # start API on :8080 (subprocess backend)
docker compose run --rm test # unit tests
```
### Compose + Docker sandbox backend
```bash
export AGENTBOX_HOST_TMP="$(pwd)/.agentbox-work"
mkdir -p "$AGENTBOX_HOST_TMP"
docker compose -f compose.yaml -f compose.docker-sandbox.yaml up --build agentbox
```
Uses image target `runtime-docker` (`docker-cli` + `AGENTBOX_SANDBOX_BACKEND=docker`), mounts the Docker socket, and bind-mounts `AGENTBOX_HOST_TMP` at the **same absolute path** so nested `docker run -v` works on Docker Desktop.
## 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 memory cap |
| `AGENTBOX_MAX_MEMORY_MB` | `8192` | Clamp requested `memory_mb` to this max |
| `AGENTBOX_SANDBOX_BACKEND` | `subprocess` | `subprocess` \| `docker` \| `unrestricted` |
| `AGENTBOX_DOCKER_IMAGE` | `python:3.12-slim` | Image for Python runs (docker backend) |
| `AGENTBOX_DOCKER_NODE_IMAGE` | `node:20-slim` | Image for JavaScript runs (docker backend) |
| `AGENTBOX_EGRESS_ALLOWLIST` | empty | Comma-separated `host[:port]`; empty = deny-all |
| `AGENTBOX_SNAPSHOT_DIR` | `/tmp/agentbox-snapshots` | Workspace snapshot store |
## Running tests
```bash
pytest tests/ -v
# Docker unit tests mock the CLI; live Docker run is skipped if docker is unavailable
pytest tests/test_docker.py -v
```
## Roadmap
- [x] Node.js runtime + TypeScript client + per-run timeout
- [x] Filesystem snapshot/restore (tar workspaces)
- [x] `limits.memory_mb` via `RLIMIT_AS` / Docker `--memory`
- [x] Default-deny egress via Linux netns (`unshare`/`bwrap`) when available
- [x] Docker ephemeral-container backend
- [x] Egress allowlists (`AGENTBOX_EGRESS_ALLOWLIST` + per-request)
- [ ] gVisor runsc backend with warm pool
- [ ] Kernel/iptables egress enforcement (beyond soft userspace hooks)
## License
MIT
## Known limitations (v0.8)
- **Subprocess** default is convenient for tests — **not production-grade isolation**; use `AGENTBOX_SANDBOX_BACKEND=docker` for stronger isolation
- Docker backend needs a local Docker CLI/daemon; missing CLI returns a clear 400
- Subprocess `RLIMIT_AS` is a soft address-space cap, not a cgroup memory controller (Docker uses `--memory`)
- Subprocess default-deny egress uses Linux `unshare`/`bwrap` when present; **macOS stays credential-scrub only** (`network_isolated: false`) unless an allowlist soft-hook applies
- Allowlists are a **soft** Python/Node userspace filter (not iptables); determined code can bypass
- Single-node, no warm pool
- TypeScript client is source-only (not published to npm)