feat(v0.5): limits_applied, oom_killed, max memory clamp

Context:
- Surface applied limits and OOM heuristic on run responses.
- Clamp memory via AGENTBOX_MAX_MEMORY_MB; expand API scenario suite.

Test Plan:
- docker compose run --rm test pytest tests/ -q
- docker compose up -d agentbox && curl /health + /v1/run scenarios

Additional Notes:
- Version 0.5.0. PyPI name is agentbox-sandbox.
This commit is contained in:
Yash Shah
2026-09-14 15:25:01 +05:30
parent 0cf92c22dc
commit 5658447185
12 changed files with 1460 additions and 12 deletions
+7
View File
@@ -1,5 +1,12 @@
# Changelog
## [0.5.0] - 2026-09-14
### Added
- Run response includes `limits_applied: {timeout_seconds, memory_mb}` (values after defaults/clamping)
- Run response includes `oom_killed` heuristic for memory-limit failures
- `AGENTBOX_MAX_MEMORY_MB` clamps requested `memory_mb` (reports clamped value in `limits_applied`)
## [0.4.0] - 2026-09-14
### Added
+3 -2
View File
@@ -6,7 +6,7 @@ Self-hosted **code execution sandbox** for AI agents — one `docker compose up`
[![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.
> **Status:** v0.5 — Python + Node subprocess sandbox, timeouts, `limits.memory_mb` / `oom_killed` / `limits_applied`, TypeScript client, workspace snapshots.
## 60-second try
@@ -37,7 +37,7 @@ Every agent that writes and runs code needs a safe execution environment. Teams
- 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)
- Per-request `limits.memory_mb` (sets `RLIMIT_AS`; 16–8192); response includes `limits_applied` + `oom_killed`
- Workspace snapshots: `"snapshot": true` then `"snapshot_id"`
- Python SDK + TypeScript client (`sdk/ts/client.ts`)
- Docker image includes Node.js for the JS runtime
@@ -118,6 +118,7 @@ docker compose run --rm test # run unit tests
| `AGENTBOX_PORT` | `8080` | Bind port |
| `AGENTBOX_DEFAULT_TIMEOUT_SECONDS` | `30` | Execution timeout |
| `AGENTBOX_DEFAULT_MEMORY_MB` | unset | Optional default `RLIMIT_AS` cap |
| `AGENTBOX_MAX_MEMORY_MB` | unset | Clamp requested `memory_mb` to this max |
| `AGENTBOX_SANDBOX_BACKEND` | `subprocess` | Backend selector |
| `AGENTBOX_SNAPSHOT_DIR` | `/tmp/agentbox-snapshots` | Workspace snapshot store |
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "agentbox-sandbox"
version = "0.4.0"
version = "0.5.0"
description = "Self-hosted code execution sandbox for AI agents"
readme = "README.md"
license = "MIT"
+18 -2
View File
@@ -2,6 +2,11 @@
* Minimal TypeScript client for agentbox.
* Usage: const box = new AgentboxClient("http://localhost:8080")
*/
export type LimitsApplied = {
timeout_seconds: number;
memory_mb: number | null;
};
export type RunResult = {
stdout: string;
stderr: string;
@@ -9,6 +14,9 @@ export type RunResult = {
duration_ms: number;
language: string;
backend: string;
snapshot_id?: string | null;
limits_applied: LimitsApplied;
oom_killed: boolean;
};
export class AgentboxClient {
@@ -20,9 +28,17 @@ export class AgentboxClient {
return res.json();
}
async run(code: string, language = "python", timeoutSeconds?: number): Promise<RunResult> {
async run(
code: string,
language = "python",
timeoutSeconds?: number,
memoryMb?: number,
): Promise<RunResult> {
const body: Record<string, unknown> = { code, language };
if (timeoutSeconds) body.limits = { timeout_seconds: timeoutSeconds };
const limits: Record<string, number> = {};
if (timeoutSeconds) limits.timeout_seconds = timeoutSeconds;
if (memoryMb != null) limits.memory_mb = memoryMb;
if (Object.keys(limits).length) body.limits = limits;
const res = await fetch(`${this.baseUrl}/v1/run`, {
method: "POST",
headers: { "content-type": "application/json" },
+1 -1
View File
@@ -1,3 +1,3 @@
"""Self-hosted code execution sandbox for AI agents."""
__version__ = "0.4.0"
__version__ = "0.5.0"
+16 -1
View File
@@ -35,6 +35,11 @@ class RunRequest(BaseModel):
snapshot_id: str | None = None
class LimitsApplied(BaseModel):
timeout_seconds: int
memory_mb: int | None = None
class RunResponse(BaseModel):
stdout: str
stderr: str
@@ -43,6 +48,8 @@ class RunResponse(BaseModel):
language: str
backend: str
snapshot_id: str | None = None
limits_applied: LimitsApplied
oom_killed: bool = False
@app.get("/health")
@@ -60,7 +67,13 @@ 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
memory_mb = (
req.limits.memory_mb
if req.limits and req.limits.memory_mb is not None
else settings.default_memory_mb
)
if memory_mb is not None:
memory_mb = min(memory_mb, settings.max_memory_mb)
try:
result = sandbox.run(
req.code,
@@ -82,4 +95,6 @@ def run_code(req: RunRequest) -> RunResponse:
language=language,
backend=settings.sandbox_backend,
snapshot_id=result.snapshot_id,
limits_applied=LimitsApplied(timeout_seconds=timeout, memory_mb=memory_mb),
oom_killed=result.oom_killed,
)
+1
View File
@@ -14,3 +14,4 @@ class Settings(BaseSettings):
sandbox_backend: str = "subprocess" # subprocess | gvisor (future)
snapshot_dir: str = "/tmp/agentbox-snapshots"
default_memory_mb: int | None = None
max_memory_mb: int = 8192
+33 -5
View File
@@ -22,6 +22,7 @@ class RunResult:
exit_code: int
duration_ms: int
snapshot_id: str | None = None
oom_killed: bool = False
class Sandbox(Protocol):
@@ -95,13 +96,17 @@ class SubprocessSandbox:
except FileNotFoundError as exc:
raise ValueError(f"Runtime not found: {exc}") from exc
new_snapshot = save_snapshot(workspace, self.snapshot_dir) if persist_snapshot else None
stdout = proc.stdout[: self.max_output_bytes]
stderr = proc.stderr[: self.max_output_bytes]
exit_code = proc.returncode
duration = int((time.monotonic() - start) * 1000)
return RunResult(
stdout=proc.stdout[: self.max_output_bytes],
stderr=proc.stderr[: self.max_output_bytes],
exit_code=proc.returncode,
stdout=stdout,
stderr=stderr,
exit_code=exit_code,
duration_ms=duration,
snapshot_id=new_snapshot,
oom_killed=_likely_oom(exit_code, stdout, stderr, mem),
)
def run_python(self, code: str) -> RunResult:
@@ -120,15 +125,38 @@ class SubprocessSandbox:
return env
def _likely_oom(exit_code: int, stdout: str, stderr: str, memory_mb: int | None) -> bool:
"""Heuristic: true when the process likely hit a memory cap.
Detects: SIGKILL/SIGSEGV exit codes (-9/-11 or 128+N), MemoryError in
stderr, or (memory limit set + nonzero exit + empty stdout). Not perfect —
RLIMIT_AS failures vary by OS/runtime.
"""
if memory_mb is None:
return False
if exit_code in (-9, -11, 137, 139):
return True
if "MemoryError" in stderr:
return True
return exit_code != 0 and stdout == ""
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)
_, 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))
try:
resource.setrlimit(
resource.RLIMIT_AS,
(cap, hard if hard != resource.RLIM_INFINITY else cap),
)
except (ValueError, OSError):
# macOS often rejects lowering RLIMIT_AS; leave uncapped on that host.
pass
return _set
+1
View File
@@ -24,6 +24,7 @@ class AgentboxClient:
snapshot_id: str | None = None,
memory_mb: int | None = None,
) -> dict[str, object]:
"""Run code; response includes limits_applied and oom_killed."""
payload: dict[str, object] = {"code": code, "language": language}
limits: dict[str, object] = {}
if timeout_seconds is not None:
+38
View File
@@ -1,6 +1,7 @@
"""Tests for agentbox API."""
import shutil
import sys
from collections.abc import Iterator
import pytest
@@ -27,6 +28,9 @@ def test_run_python(client: TestClient) -> None:
body = resp.json()
assert "hello agentbox" in body["stdout"]
assert body["exit_code"] == 0
assert body["limits_applied"]["timeout_seconds"] >= 1
assert "memory_mb" in body["limits_applied"]
assert body["oom_killed"] is False
def test_run_rejects_unknown_language(client: TestClient) -> None:
@@ -83,6 +87,7 @@ def test_unknown_snapshot_returns_400(client: TestClient) -> None:
assert resp.status_code == 400
@pytest.mark.skipif(sys.platform == "darwin", reason="RLIMIT_AS not enforceable on macOS")
def test_memory_limit_kills_huge_allocation(client: TestClient) -> None:
resp = client.post(
"/v1/run",
@@ -96,3 +101,36 @@ def test_memory_limit_kills_huge_allocation(client: TestClient) -> None:
# 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", "")
assert body["limits_applied"] == {"timeout_seconds": 5, "memory_mb": 32}
assert body["oom_killed"] is True
def test_oom_killed_on_memory_error(client: TestClient) -> None:
resp = client.post(
"/v1/run",
json={
"code": "raise MemoryError('simulated')",
"limits": {"memory_mb": 64, "timeout_seconds": 5},
},
)
assert resp.status_code == 200
body = resp.json()
assert body["exit_code"] != 0
assert body["oom_killed"] is True
assert body["limits_applied"]["memory_mb"] == 64
def test_memory_clamped_to_max(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr("agentbox.api.app.settings.max_memory_mb", 64)
resp = client.post(
"/v1/run",
json={
"code": "print('ok')",
"limits": {"memory_mb": 256, "timeout_seconds": 10},
},
)
assert resp.status_code == 200
body = resp.json()
assert body["limits_applied"]["memory_mb"] == 64
assert body["limits_applied"]["timeout_seconds"] == 10
assert "ok" in body["stdout"]
+244
View File
@@ -0,0 +1,244 @@
"""Scenario tests for agentbox 0.5 API behavior."""
from __future__ import annotations
import inspect
import shutil
from collections.abc import Iterator
import pytest
from fastapi.testclient import TestClient
from agentbox import __version__
from agentbox.api.app import app
from agentbox.sdk.client import AgentboxClient
@pytest.fixture
def client() -> Iterator[TestClient]:
with TestClient(app) as test_client:
yield test_client
def test_health_version_050(client: TestClient) -> None:
resp = client.get("/health")
assert resp.status_code == 200
body = resp.json()
assert body["status"] == "ok"
assert body["version"] == "0.5.0"
assert __version__ == "0.5.0"
def test_python_success(client: TestClient) -> None:
resp = client.post("/v1/run", json={"code": "print('hello agentbox')"})
assert resp.status_code == 200
body = resp.json()
assert "hello agentbox" in body["stdout"]
assert body["exit_code"] == 0
assert body["language"] == "python"
assert body["oom_killed"] is False
def test_javascript_success(client: TestClient) -> None:
if shutil.which("node") is None:
pytest.skip("node not installed")
resp = client.post(
"/v1/run",
json={"code": "console.log('hello node')", "language": "javascript"},
)
assert resp.status_code == 200
body = resp.json()
assert "hello node" in body["stdout"]
assert body["exit_code"] == 0
def test_reject_unknown_language(client: TestClient) -> None:
resp = client.post("/v1/run", json={"code": "puts 1", "language": "ruby"})
assert resp.status_code == 400
assert "Unsupported language" in resp.json()["detail"]
def test_reject_language_rust(client: TestClient) -> None:
resp = client.post("/v1/run", json={"code": "fn main() {}", "language": "rust"})
assert resp.status_code == 400
def test_timeout_returns_408(client: TestClient) -> None:
resp = client.post(
"/v1/run",
json={
"code": "import time; time.sleep(5)",
"limits": {"timeout_seconds": 1},
},
)
assert resp.status_code == 408
def test_memory_oom_killed_true(client: TestClient) -> None:
resp = client.post(
"/v1/run",
json={
"code": "raise MemoryError('simulated')",
"limits": {"memory_mb": 64, "timeout_seconds": 5},
},
)
assert resp.status_code == 200
body = resp.json()
assert body["exit_code"] != 0
assert body["oom_killed"] is True
def test_limits_applied_present(client: TestClient) -> None:
resp = client.post(
"/v1/run",
json={
"code": "print('ok')",
"limits": {"memory_mb": 128, "timeout_seconds": 7},
},
)
assert resp.status_code == 200
body = resp.json()
assert body["limits_applied"] == {"timeout_seconds": 7, "memory_mb": 128}
assert "ok" in body["stdout"]
def test_max_memory_clamp(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr("agentbox.api.app.settings.max_memory_mb", 64)
resp = client.post(
"/v1/run",
json={
"code": "print('clamped')",
"limits": {"memory_mb": 512, "timeout_seconds": 10},
},
)
assert resp.status_code == 200
body = resp.json()
assert body["limits_applied"]["memory_mb"] == 64
assert body["limits_applied"]["timeout_seconds"] == 10
assert "clamped" in body["stdout"]
def test_snapshot_restore(client: TestClient) -> None:
first = client.post(
"/v1/run",
json={"code": "open('memo.txt','w').write('kept')", "snapshot": True},
)
assert first.status_code == 200
snapshot_id = first.json()["snapshot_id"]
assert snapshot_id
second = client.post(
"/v1/run",
json={
"code": "print(open('memo.txt').read())",
"snapshot_id": snapshot_id,
},
)
assert second.status_code == 200
assert "kept" in second.json()["stdout"]
def test_unknown_snapshot_returns_400(client: TestClient) -> None:
resp = client.post(
"/v1/run",
json={"code": "print(1)", "snapshot_id": "does-not-exist"},
)
assert resp.status_code == 400
def test_stderr_nonzero_exit(client: TestClient) -> None:
resp = client.post(
"/v1/run",
json={"code": "import sys; print('err', file=sys.stderr); sys.exit(3)"},
)
assert resp.status_code == 200
body = resp.json()
assert body["exit_code"] == 3
assert "err" in body["stderr"]
def test_stderr_exception_exit(client: TestClient) -> None:
resp = client.post(
"/v1/run",
json={"code": "raise RuntimeError('boom')"},
)
assert resp.status_code == 200
body = resp.json()
assert body["exit_code"] != 0
assert "boom" in body["stderr"] or "RuntimeError" in body["stderr"]
def test_empty_code_rejected(client: TestClient) -> None:
resp = client.post("/v1/run", json={"code": ""})
assert resp.status_code == 422
def test_syntax_error_nonzero(client: TestClient) -> None:
resp = client.post("/v1/run", json={"code": "def ("})
assert resp.status_code == 200
body = resp.json()
assert body["exit_code"] != 0
assert body["stderr"] != ""
def test_sdk_client_fields_signature() -> None:
sig = inspect.signature(AgentboxClient.run)
for name in ("code", "language", "timeout_seconds", "snapshot", "snapshot_id", "memory_mb"):
assert name in sig.parameters
client = AgentboxClient(base_url="http://localhost:8080")
assert client.base_url == "http://localhost:8080"
assert hasattr(client, "health")
client.close()
def test_sdk_client_run_response_fields(client: TestClient) -> None:
"""SDK documents limits_applied + oom_killed; exercise via TestClient + payload shape."""
api = client.post(
"/v1/run",
json={"code": "print(42)", "limits": {"memory_mb": 64, "timeout_seconds": 10}},
)
assert api.status_code == 200
body = api.json()
assert "limits_applied" in body
assert body["limits_applied"]["memory_mb"] == 64
assert body["limits_applied"]["timeout_seconds"] == 10
assert "oom_killed" in body
captured: dict[str, object] = {}
class _Resp:
status_code = 200
@staticmethod
def json() -> dict[str, object]:
return body
sdk = AgentboxClient(base_url="http://test")
def _post(_url: str, json: dict[str, object] | None = None) -> _Resp:
captured["payload"] = json
return _Resp()
sdk._client.post = _post # type: ignore[method-assign]
try:
result = sdk.run("print(42)", memory_mb=64, timeout_seconds=10, snapshot=True)
assert captured["payload"] == {
"code": "print(42)",
"language": "python",
"limits": {"timeout_seconds": 10, "memory_mb": 64},
"snapshot": True,
}
assert result["limits_applied"]["memory_mb"] == 64
assert "oom_killed" in result
finally:
sdk.close()
def test_node_language_alias(client: TestClient) -> None:
if shutil.which("node") is None:
pytest.skip("node not installed")
resp = client.post(
"/v1/run",
json={"code": "console.log('via node')", "language": "node"},
)
assert resp.status_code == 200
assert "via node" in resp.json()["stdout"]
Generated
+1097
View File
File diff suppressed because it is too large Load Diff