mirror of
https://github.com/yashshah9/agentbox.git
synced 2026-11-18 18:03:44 +00:00
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.
This commit is contained in:
@@ -1,5 +1,11 @@
|
||||
# Changelog
|
||||
|
||||
## [0.4.0] - 2026-09-14
|
||||
|
||||
### Added
|
||||
- `limits.memory_mb` on `POST /v1/run` — applies `RLIMIT_AS` in the child process (16–8192 MB)
|
||||
- Optional `AGENTBOX_DEFAULT_MEMORY_MB` and SDK `memory_mb=` passthrough
|
||||
|
||||
## [0.3.0] - 2026-08-19
|
||||
|
||||
### Added
|
||||
|
||||
+20
-5
@@ -1,5 +1,16 @@
|
||||
# Contributing
|
||||
|
||||
## Running tests
|
||||
|
||||
Prefer Docker Compose:
|
||||
|
||||
```bash
|
||||
docker compose run --rm test
|
||||
docker compose up agentbox # API on :8080 for manual checks
|
||||
```
|
||||
|
||||
Locally:
|
||||
|
||||
```bash
|
||||
pip install -e ".[dev]"
|
||||
pytest tests/ -v
|
||||
@@ -7,9 +18,13 @@ agentbox serve
|
||||
curl http://localhost:8080/health
|
||||
```
|
||||
|
||||
Docker:
|
||||
## Pull requests
|
||||
|
||||
```bash
|
||||
docker compose up agentbox
|
||||
docker compose run --rm test
|
||||
```
|
||||
- Treat sandbox changes as security-sensitive; document limitations honestly
|
||||
- Update README/CHANGELOG for API or limit changes
|
||||
- Prefer small PRs with a clear test plan
|
||||
|
||||
## Commit style
|
||||
|
||||
- Imperative subject line; mention the user-facing why when relevant
|
||||
- Do not add AI co-author trailers (e.g. Co-authored-by: Cursor) to commits.
|
||||
|
||||
@@ -2,16 +2,42 @@
|
||||
|
||||
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.3 — Python + Node subprocess sandbox, per-run timeouts, TypeScript client, workspace snapshots.
|
||||
[](LICENSE)
|
||||
[](https://www.python.org/downloads/)
|
||||
[](https://github.com/yashshah9/agentbox/actions/workflows/ci.yml)
|
||||
|
||||
> **Status:** v0.4 — Python + Node subprocess sandbox, timeouts, `limits.memory_mb` via `RLIMIT_AS`, TypeScript client, workspace snapshots.
|
||||
|
||||
## 60-second try
|
||||
|
||||
```bash
|
||||
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.2)
|
||||
## 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
|
||||
@@ -56,6 +82,10 @@ docker compose up agentbox
|
||||
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
|
||||
@@ -67,6 +97,7 @@ 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()
|
||||
@@ -86,6 +117,7 @@ docker compose run --rm test # run unit tests
|
||||
| `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 |
|
||||
|
||||
@@ -99,6 +131,7 @@ pytest tests/ -v
|
||||
|
||||
- [x] Node.js runtime + TypeScript client + per-run timeout
|
||||
- [x] Filesystem snapshot/restore (tar workspaces)
|
||||
- [x] `limits.memory_mb` via `RLIMIT_AS`
|
||||
- [ ] gVisor runsc backend with warm pool
|
||||
- [ ] Default-deny egress with allowlists (kernel netns)
|
||||
|
||||
@@ -106,9 +139,10 @@ pytest tests/ -v
|
||||
|
||||
MIT
|
||||
|
||||
## Known limitations (v0.3)
|
||||
## 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)
|
||||
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
# Security Policy
|
||||
|
||||
## Reporting a vulnerability
|
||||
|
||||
Email **yash376351@gmail.com** with the repo name, a short description, and steps to reproduce. Please do not open a public issue for exploitable findings until we have had a reasonable chance to respond.
|
||||
|
||||
## Threat model (honest)
|
||||
|
||||
agentbox executes **untrusted code** on your machine via a subprocess sandbox.
|
||||
|
||||
- The current backend is **subprocess + optional `RLIMIT_AS`**, not gVisor/Firecracker. Do **not** expose it to the public internet as-is.
|
||||
- Credential stripping and timeouts reduce accidents; they are **not** a kernel isolation story.
|
||||
- `limits.memory_mb` caps address space via `RLIMIT_AS` — it is not a cgroup memory controller and behavior differs by OS.
|
||||
- Snapshots persist workspace files on disk under `AGENTBOX_SNAPSHOT_DIR`.
|
||||
- Prefer running the API only on trusted networks, behind auth you add yourself.
|
||||
+7
-1
@@ -4,11 +4,12 @@ build-backend = "hatchling.build"
|
||||
|
||||
[project]
|
||||
name = "agentbox"
|
||||
version = "0.3.0"
|
||||
version = "0.4.0"
|
||||
description = "Self-hosted code execution sandbox for AI agents"
|
||||
readme = "README.md"
|
||||
license = "MIT"
|
||||
requires-python = ">=3.11"
|
||||
authors = [{ name = "Yash Shah", email = "yash376351@gmail.com" }]
|
||||
dependencies = [
|
||||
"fastapi>=0.111",
|
||||
"pydantic>=2.6",
|
||||
@@ -17,6 +18,11 @@ dependencies = [
|
||||
"uvicorn[standard]>=0.29",
|
||||
]
|
||||
|
||||
[project.urls]
|
||||
Homepage = "https://github.com/yashshah9/agentbox"
|
||||
Repository = "https://github.com/yashshah9/agentbox"
|
||||
Issues = "https://github.com/yashshah9/agentbox/issues"
|
||||
|
||||
[project.optional-dependencies]
|
||||
dev = ["pytest>=8.0", "httpx>=0.27", "ruff>=0.4", "mypy>=1.9"]
|
||||
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
"""Self-hosted code execution sandbox for AI agents."""
|
||||
|
||||
__version__ = "0.3.0"
|
||||
__version__ = "0.4.0"
|
||||
|
||||
@@ -15,6 +15,7 @@ sandbox = SubprocessSandbox(
|
||||
max_output_bytes=settings.max_output_bytes,
|
||||
deny_egress=settings.sandbox_backend != "unrestricted",
|
||||
snapshot_dir=settings.snapshot_dir,
|
||||
default_memory_mb=settings.default_memory_mb,
|
||||
)
|
||||
|
||||
app = FastAPI(title="agentbox", version=__version__)
|
||||
@@ -23,6 +24,7 @@ app = FastAPI(title="agentbox", version=__version__)
|
||||
class ResourceLimits(BaseModel):
|
||||
timeout_seconds: int | None = Field(default=None, ge=1, le=300)
|
||||
max_output_bytes: int | None = Field(default=None, ge=1024)
|
||||
memory_mb: int | None = Field(default=None, ge=16, le=8192)
|
||||
|
||||
|
||||
class RunRequest(BaseModel):
|
||||
@@ -58,6 +60,7 @@ def run_code(req: RunRequest) -> RunResponse:
|
||||
if req.limits and req.limits.timeout_seconds
|
||||
else settings.default_timeout_seconds
|
||||
)
|
||||
memory_mb = req.limits.memory_mb if req.limits else None
|
||||
try:
|
||||
result = sandbox.run(
|
||||
req.code,
|
||||
@@ -65,6 +68,7 @@ def run_code(req: RunRequest) -> RunResponse:
|
||||
timeout_seconds=timeout,
|
||||
snapshot_id=req.snapshot_id,
|
||||
persist_snapshot=req.snapshot,
|
||||
memory_mb=memory_mb,
|
||||
)
|
||||
except subprocess.TimeoutExpired as exc:
|
||||
raise HTTPException(status_code=408, detail="Execution timed out") from exc
|
||||
|
||||
@@ -13,3 +13,4 @@ class Settings(BaseSettings):
|
||||
max_output_bytes: int = 1_048_576
|
||||
sandbox_backend: str = "subprocess" # subprocess | gvisor (future)
|
||||
snapshot_dir: str = "/tmp/agentbox-snapshots"
|
||||
default_memory_mb: int | None = None
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import resource
|
||||
import shutil
|
||||
import subprocess
|
||||
import tempfile
|
||||
@@ -29,7 +30,7 @@ class Sandbox(Protocol):
|
||||
|
||||
|
||||
class SubprocessSandbox:
|
||||
"""MVP sandbox: isolated temp directory + subprocess timeout.
|
||||
"""MVP sandbox: isolated temp directory + subprocess timeout + optional memory cap.
|
||||
|
||||
ponytail: not production isolation — upgrade path is gVisor/docker backend.
|
||||
"""
|
||||
@@ -40,11 +41,13 @@ class SubprocessSandbox:
|
||||
max_output_bytes: int = 1_048_576,
|
||||
deny_egress: bool = False,
|
||||
snapshot_dir: str | Path | None = None,
|
||||
default_memory_mb: int | None = None,
|
||||
) -> None:
|
||||
self.timeout_seconds = timeout_seconds
|
||||
self.max_output_bytes = max_output_bytes
|
||||
self.deny_egress = deny_egress
|
||||
self.snapshot_dir = Path(snapshot_dir) if snapshot_dir else Path("/tmp/agentbox-snapshots")
|
||||
self.default_memory_mb = default_memory_mb
|
||||
|
||||
def run(
|
||||
self,
|
||||
@@ -53,8 +56,10 @@ class SubprocessSandbox:
|
||||
timeout_seconds: int | None = None,
|
||||
snapshot_id: str | None = None,
|
||||
persist_snapshot: bool = False,
|
||||
memory_mb: int | None = None,
|
||||
) -> RunResult:
|
||||
timeout = timeout_seconds or self.timeout_seconds
|
||||
mem = memory_mb if memory_mb is not None else self.default_memory_mb
|
||||
start = time.monotonic()
|
||||
env = self._env()
|
||||
with tempfile.TemporaryDirectory(prefix="agentbox-") as tmp:
|
||||
@@ -75,6 +80,7 @@ class SubprocessSandbox:
|
||||
argv = [node, str(script)]
|
||||
else:
|
||||
raise ValueError(f"Unsupported language: {language}")
|
||||
preexec = _memory_preexec(mem) if mem else None
|
||||
try:
|
||||
proc = subprocess.run(
|
||||
argv,
|
||||
@@ -84,6 +90,7 @@ class SubprocessSandbox:
|
||||
cwd=tmp,
|
||||
env=env,
|
||||
check=False,
|
||||
preexec_fn=preexec,
|
||||
)
|
||||
except FileNotFoundError as exc:
|
||||
raise ValueError(f"Runtime not found: {exc}") from exc
|
||||
@@ -111,3 +118,17 @@ class SubprocessSandbox:
|
||||
env.pop("AWS_SECRET_ACCESS_KEY", None)
|
||||
env.pop("OPENAI_API_KEY", None)
|
||||
return env
|
||||
|
||||
|
||||
def _memory_preexec(memory_mb: int):
|
||||
"""Return a preexec_fn that caps address space for the child process."""
|
||||
|
||||
bytes_limit = max(1, memory_mb) * 1024 * 1024
|
||||
|
||||
def _set() -> None:
|
||||
soft, hard = resource.getrlimit(resource.RLIMIT_AS)
|
||||
# Keep within existing hard limit when the OS publishes one.
|
||||
cap = bytes_limit if hard == resource.RLIM_INFINITY else min(bytes_limit, hard)
|
||||
resource.setrlimit(resource.RLIMIT_AS, (cap, hard if hard != resource.RLIM_INFINITY else cap))
|
||||
|
||||
return _set
|
||||
|
||||
@@ -22,10 +22,16 @@ class AgentboxClient:
|
||||
timeout_seconds: int | None = None,
|
||||
snapshot: bool = False,
|
||||
snapshot_id: str | None = None,
|
||||
memory_mb: int | None = None,
|
||||
) -> dict[str, object]:
|
||||
payload: dict[str, object] = {"code": code, "language": language}
|
||||
limits: dict[str, object] = {}
|
||||
if timeout_seconds is not None:
|
||||
payload["limits"] = {"timeout_seconds": timeout_seconds}
|
||||
limits["timeout_seconds"] = timeout_seconds
|
||||
if memory_mb is not None:
|
||||
limits["memory_mb"] = memory_mb
|
||||
if limits:
|
||||
payload["limits"] = limits
|
||||
if snapshot:
|
||||
payload["snapshot"] = True
|
||||
if snapshot_id:
|
||||
|
||||
@@ -81,3 +81,18 @@ def test_unknown_snapshot_returns_400(client: TestClient) -> None:
|
||||
json={"code": "print(1)", "snapshot_id": "does-not-exist"},
|
||||
)
|
||||
assert resp.status_code == 400
|
||||
|
||||
|
||||
def test_memory_limit_kills_huge_allocation(client: TestClient) -> None:
|
||||
resp = client.post(
|
||||
"/v1/run",
|
||||
json={
|
||||
"code": "x = bytearray(200 * 1024 * 1024); print(len(x))",
|
||||
"limits": {"memory_mb": 32, "timeout_seconds": 5},
|
||||
},
|
||||
)
|
||||
assert resp.status_code == 200
|
||||
body = resp.json()
|
||||
# RLIMIT_AS should prevent the allocation from succeeding.
|
||||
assert body["exit_code"] != 0 or "MemoryError" in body["stderr"] or body["stdout"] == ""
|
||||
assert "209715200" not in body.get("stdout", "")
|
||||
|
||||
Reference in New Issue
Block a user