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:
Yash Shah
2026-09-14 14:00:42 +05:30
parent f0045a3a5f
commit a21089184b
11 changed files with 135 additions and 12 deletions
+6
View File
@@ -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
View File
@@ -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.
+37 -3
View File
@@ -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: 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.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
View File
@@ -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
View File
@@ -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 -1
View File
@@ -1,3 +1,3 @@
"""Self-hosted code execution sandbox for AI agents."""
__version__ = "0.3.0"
__version__ = "0.4.0"
+4
View File
@@ -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
+1
View File
@@ -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
+22 -1
View File
@@ -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
+7 -1
View File
@@ -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:
+15
View File
@@ -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", "")