Yash Shah a21089184b feat(v0.4): enforce per-run memory_mb via RLIMIT_AS
Context:
- Timeout alone does not stop runaway memory allocations in agent-generated code.
- Docs understated that subprocess is not production isolation.

Test Plan:
- docker compose run --rm test
- tests/test_api.py::test_memory_limit_kills_huge_allocation

Additional Notes:
- limits.memory_mb uses resource.RLIMIT_AS via preexec_fn (Linux Docker).
- Adoption: badges, SECURITY.md, CONTRIBUTING, author/urls.
2026-09-14 14:00:42 +05:30

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.

License: MIT Python 3.11+ CI

Status: v0.4 — Python + Node subprocess sandbox, timeouts, limits.memory_mb via RLIMIT_AS, TypeScript client, workspace snapshots.

60-second try

docker compose up agentbox        # API on :8080
# in another shell:
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)))"}'
docker compose run --rm test      # pytest

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.4)

  • 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 in the child process; 16–8192)
  • 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

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
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_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_mb via RLIMIT_AS
  • gVisor runsc backend with warm pool
  • Default-deny egress with allowlists (kernel netns)

License

MIT

Known limitations (v0.4)

  • Subprocess sandbox only — not production-grade isolation
  • RLIMIT_AS is a soft address-space cap, not a cgroup memory controller
  • Credential stripping is not a network namespace
  • Single-node, no warm pool
  • TypeScript client is source-only (not published to npm)
S
Description
No description provided
Readme MIT
189 KiB
Languages
Python 95.9%
TypeScript 2.6%
Dockerfile 1.5%