diff --git a/CHANGELOG.md b/CHANGELOG.md index b6ac705..bf66739 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7ba387d..4670e25 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index fc62c2e..dcf8013 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..4c4084a --- /dev/null +++ b/SECURITY.md @@ -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. diff --git a/pyproject.toml b/pyproject.toml index 063050f..c437d91 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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"] diff --git a/src/agentbox/__init__.py b/src/agentbox/__init__.py index 668e047..c017642 100644 --- a/src/agentbox/__init__.py +++ b/src/agentbox/__init__.py @@ -1,3 +1,3 @@ """Self-hosted code execution sandbox for AI agents.""" -__version__ = "0.3.0" +__version__ = "0.4.0" diff --git a/src/agentbox/api/app.py b/src/agentbox/api/app.py index 5d87192..3ecb353 100644 --- a/src/agentbox/api/app.py +++ b/src/agentbox/api/app.py @@ -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 diff --git a/src/agentbox/config.py b/src/agentbox/config.py index 9de4672..14af908 100644 --- a/src/agentbox/config.py +++ b/src/agentbox/config.py @@ -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 diff --git a/src/agentbox/sandbox/runner.py b/src/agentbox/sandbox/runner.py index bac31a6..1be3fc2 100644 --- a/src/agentbox/sandbox/runner.py +++ b/src/agentbox/sandbox/runner.py @@ -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 diff --git a/src/agentbox/sdk/client.py b/src/agentbox/sdk/client.py index 58b8284..0ca5379 100644 --- a/src/agentbox/sdk/client.py +++ b/src/agentbox/sdk/client.py @@ -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: diff --git a/tests/test_api.py b/tests/test_api.py index 8d79230..d951eff 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -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", "")