fix(api): snapshot files only and surface HTTP errors in the SDK

Context:
- tar.add on directories recursively re-included main.py/main.js that snapshot restore is supposed to skip.
- AgentboxClient.raise_for_status turned expected 408 timeouts into opaque httpx errors.
- Missing runtimes returned HTTP 200 with exit 127 instead of 400.

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

Additional Notes:
- health CLI now prints the package version, matching the other five CLIs.
- TestClient is used as a context manager to avoid the Starlette lifespan warning path.
This commit is contained in:
Yash Shah
2026-08-19 11:57:34 +05:30
parent 67495fc374
commit f0045a3a5f
7 changed files with 45 additions and 17 deletions
+6 -2
View File
@@ -12,6 +12,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)
- 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`
@@ -66,6 +67,8 @@ client = AgentboxClient("http://localhost:8080")
print(client.health())
print(client.run("print('hello')"))
print(client.run("console.log('hello')", language="javascript", timeout_seconds=5))
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()
```
@@ -84,6 +87,7 @@ docker compose run --rm test # run unit tests
| `AGENTBOX_PORT` | `8080` | Bind port |
| `AGENTBOX_DEFAULT_TIMEOUT_SECONDS` | `30` | Execution timeout |
| `AGENTBOX_SANDBOX_BACKEND` | `subprocess` | Backend selector |
| `AGENTBOX_SNAPSHOT_DIR` | `/tmp/agentbox-snapshots` | Workspace snapshot store |
## Running tests
@@ -94,15 +98,15 @@ pytest tests/ -v
## Roadmap
- [x] Node.js runtime + TypeScript client + per-run timeout
- [x] Filesystem snapshot/restore (tar workspaces)
- [ ] gVisor runsc backend with warm pool
- [ ] Filesystem snapshot/restore
- [ ] Default-deny egress with allowlists (kernel netns)
## License
MIT
## Known limitations (v0.2)
## Known limitations (v0.3)
- Subprocess sandbox only — **not production-grade isolation**
- Credential stripping is not a network namespace
+1
View File
@@ -9,6 +9,7 @@ services:
environment:
AGENTBOX_LOG_LEVEL: INFO
AGENTBOX_DEFAULT_TIMEOUT_SECONDS: 30
AGENTBOX_SNAPSHOT_DIR: /tmp/agentbox-snapshots
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health')"]
interval: 10s
+3 -1
View File
@@ -3,10 +3,12 @@
import click
import uvicorn
from agentbox import __version__
from agentbox.config import Settings
@click.group()
@click.version_option(__version__)
def main() -> None:
"""Self-hosted code execution sandbox for AI agents."""
@@ -26,7 +28,7 @@ def serve(host: str | None, port: int | None) -> None:
@main.command("health")
def health_cmd() -> None:
click.echo("agentbox OK")
click.echo(f"agentbox {__version__} OK")
if __name__ == "__main__":
+2 -1
View File
@@ -83,9 +83,10 @@ class SubprocessSandbox:
timeout=timeout,
cwd=tmp,
env=env,
check=False,
)
except FileNotFoundError as exc:
return RunResult("", str(exc), 127, int((time.monotonic() - start) * 1000))
raise ValueError(f"Runtime not found: {exc}") from exc
new_snapshot = save_snapshot(workspace, self.snapshot_dir) if persist_snapshot else None
duration = int((time.monotonic() - start) * 1000)
return RunResult(
+1 -1
View File
@@ -13,7 +13,7 @@ def save_snapshot(workspace: Path, snapshot_dir: Path) -> str:
archive = snapshot_dir / f"{snapshot_id}.tar.gz"
with tarfile.open(archive, "w:gz") as tar:
for path in workspace.rglob("*"):
if path.name in {"main.py", "main.js"}:
if not path.is_file() or path.name in {"main.py", "main.js"}:
continue
tar.add(path, arcname=path.relative_to(workspace))
return snapshot_id
+19 -4
View File
@@ -1,5 +1,7 @@
"""Python SDK client."""
from typing import Any, cast
import httpx
@@ -10,8 +12,8 @@ class AgentboxClient:
def health(self) -> dict[str, str]:
resp = self._client.get("/health")
resp.raise_for_status()
return resp.json()
self._raise_for_status(resp)
return cast(dict[str, str], resp.json())
def run(
self,
@@ -29,8 +31,21 @@ class AgentboxClient:
if snapshot_id:
payload["snapshot_id"] = snapshot_id
resp = self._client.post("/v1/run", json=payload)
resp.raise_for_status()
return resp.json()
self._raise_for_status(resp)
return cast(dict[str, object], resp.json())
def close(self) -> None:
self._client.close()
@staticmethod
def _raise_for_status(resp: httpx.Response) -> None:
if resp.status_code < 400:
return
detail: object = resp.text
try:
body: Any = resp.json()
except ValueError:
body = None
if isinstance(body, dict):
detail = body.get("detail", body)
raise RuntimeError(f"agentbox HTTP {resp.status_code}: {detail}")
+13 -8
View File
@@ -1,22 +1,27 @@
"""Tests for agentbox API."""
import shutil
from collections.abc import Iterator
import pytest
from fastapi.testclient import TestClient
from agentbox.api.app import app
client = TestClient(app)
@pytest.fixture
def client() -> Iterator[TestClient]:
with TestClient(app) as test_client:
yield test_client
def test_health() -> None:
def test_health(client: TestClient) -> None:
resp = client.get("/health")
assert resp.status_code == 200
assert resp.json()["status"] == "ok"
def test_run_python() -> None:
def test_run_python(client: TestClient) -> None:
resp = client.post("/v1/run", json={"code": "print('hello agentbox')"})
assert resp.status_code == 200
body = resp.json()
@@ -24,12 +29,12 @@ def test_run_python() -> None:
assert body["exit_code"] == 0
def test_run_rejects_unknown_language() -> None:
def test_run_rejects_unknown_language(client: TestClient) -> None:
resp = client.post("/v1/run", json={"code": "print(1)", "language": "ruby"})
assert resp.status_code == 400
def test_run_timeout_limit() -> None:
def test_run_timeout_limit(client: TestClient) -> None:
resp = client.post(
"/v1/run",
json={
@@ -41,7 +46,7 @@ def test_run_timeout_limit() -> None:
@pytest.mark.skipif(shutil.which("node") is None, reason="node not installed")
def test_run_javascript() -> None:
def test_run_javascript(client: TestClient) -> None:
resp = client.post(
"/v1/run",
json={"code": "console.log('hello node')", "language": "javascript"},
@@ -51,7 +56,7 @@ def test_run_javascript() -> None:
assert resp.json()["exit_code"] == 0
def test_snapshot_restore_keeps_workspace_file() -> None:
def test_snapshot_restore_keeps_workspace_file(client: TestClient) -> None:
first = client.post(
"/v1/run",
json={"code": "open('memo.txt','w').write('kept')", "snapshot": True},
@@ -70,7 +75,7 @@ def test_snapshot_restore_keeps_workspace_file() -> None:
assert "kept" in second.json()["stdout"]
def test_unknown_snapshot_returns_400() -> None:
def test_unknown_snapshot_returns_400(client: TestClient) -> None:
resp = client.post(
"/v1/run",
json={"code": "print(1)", "snapshot_id": "does-not-exist"},