mirror of
https://github.com/yashshah9/agentbox.git
synced 2026-11-18 18:03:44 +00:00
feat(v0.2): add Node runtime, per-run timeouts, and TypeScript client
Context: - Python-only subprocess runs were not enough for agent sandboxes. - Execute JavaScript, honor per-request timeouts, and ship a fetch-based TS client. Test Plan: - docker compose build test && docker compose run --rm test - POST /v1/run with language javascript and limits.timeout_seconds=1 Additional Notes: - Isolation is still subprocess, not gVisor.
This commit is contained in:
@@ -1,5 +1,16 @@
|
||||
# Changelog
|
||||
|
||||
## [0.2.0] - 2026-08-19
|
||||
|
||||
### Added
|
||||
- JavaScript/Node runtime (`language: javascript|node`)
|
||||
- Per-request `limits.timeout_seconds` (408 on timeout)
|
||||
- TypeScript client at `sdk/ts/client.ts`
|
||||
- Credential stripping when backend is not `unrestricted`
|
||||
|
||||
### Notes
|
||||
- Isolation is still subprocess, not gVisor
|
||||
|
||||
## [0.1.0] - 2026-08-18
|
||||
|
||||
### Added
|
||||
|
||||
@@ -2,19 +2,19 @@
|
||||
|
||||
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.1 foundation — FastAPI service with subprocess sandbox; gVisor/docker backends and snapshots are next.
|
||||
> **Status:** v0.2 — Python + Node subprocess sandbox, per-run timeouts, TypeScript client. gVisor isolation is next.
|
||||
|
||||
## 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.1)
|
||||
## Key features (v0.2)
|
||||
|
||||
- HTTP API: `POST /v1/run` executes Python code
|
||||
- Health endpoint for orchestration
|
||||
- Python SDK client
|
||||
- Configurable timeout and output limits
|
||||
- Docker Compose single-node deployment
|
||||
- HTTP API: `POST /v1/run` executes Python or JavaScript
|
||||
- Per-request `limits.timeout_seconds` (HTTP 408 on timeout)
|
||||
- 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`
|
||||
|
||||
## Architecture
|
||||
|
||||
@@ -65,6 +65,7 @@ from agentbox.sdk.client import AgentboxClient
|
||||
client = AgentboxClient("http://localhost:8080")
|
||||
print(client.health())
|
||||
print(client.run("print('hello')"))
|
||||
print(client.run("console.log('hello')", language="javascript", timeout_seconds=5))
|
||||
client.close()
|
||||
```
|
||||
|
||||
@@ -92,18 +93,18 @@ pytest tests/ -v
|
||||
|
||||
## Roadmap
|
||||
|
||||
- [x] Node.js runtime + TypeScript client + per-run timeout
|
||||
- [ ] gVisor runsc backend with warm pool
|
||||
- [ ] Filesystem snapshot/restore
|
||||
- [ ] Node.js and shell runtimes
|
||||
- [ ] Default-deny egress with allowlists
|
||||
- [ ] Default-deny egress with allowlists (kernel netns)
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
## Known limitations (v0.1)
|
||||
## Known limitations (v0.2)
|
||||
|
||||
- Subprocess sandbox only — **not production-grade isolation**
|
||||
- Python runtime only
|
||||
- Credential stripping is not a network namespace
|
||||
- Single-node, no warm pool
|
||||
- No filesystem write API beyond temp script
|
||||
- TypeScript client is source-only (not published to npm)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
FROM python:3.12-slim AS base
|
||||
WORKDIR /app
|
||||
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends nodejs && rm -rf /var/lib/apt/lists/*
|
||||
|
||||
FROM base AS dev
|
||||
COPY pyproject.toml README.md ./
|
||||
|
||||
+1
-1
@@ -3,4 +3,4 @@
|
||||
| Document | Status | Description |
|
||||
|----------|--------|-------------|
|
||||
| [v0.1-completed-foundation.md](./v0.1-completed-foundation.md) | **Completed** | Initial foundation release |
|
||||
| [v0.2-next-phase-roadmap.md](./v0.2-next-phase-roadmap.md) | **Planned** | Next-phase improvements |
|
||||
| [v0.2-next-phase-roadmap.md](./v0.2-next-phase-roadmap.md) | **In Progress** | v0.2.0 shipped Node + timeouts + TS client; gVisor still open |
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Version target** | 0.2.x |
|
||||
| **Status** | Planned |
|
||||
| **Status** | v0.2.0 shipped (Node runtime, TS client, per-run timeout; gVisor/pool/snapshots still open) |
|
||||
| **Owner** | Yash Shah |
|
||||
| **Planning date** | August 2026 |
|
||||
| **Depends on** | [v0.1-completed-foundation.md](./v0.1-completed-foundation.md) (shipped 2026-08-18) |
|
||||
@@ -114,7 +114,7 @@ Replace subprocess isolation with **gVisor `runsc`** OCI runtime so untrusted co
|
||||
- [ ] Attempt to bind/listen on network fails with `--network=none`.
|
||||
- [ ] Execution timeout kills runsc container within `timeout + 2s` grace.
|
||||
- [ ] `/health` returns `"backend": "runsc"` when configured.
|
||||
- [ ] Subprocess backend still works when `AGENTBOX_SANDBOX_BACKEND=subprocess`.
|
||||
- [x] Subprocess backend still works when `AGENTBOX_SANDBOX_BACKEND=subprocess`.
|
||||
- [ ] ≥5 integration tests pass in CI (happy path, timeout, exit non-zero, output cap, isolation).
|
||||
|
||||
### Risks
|
||||
@@ -266,12 +266,12 @@ Execute **JavaScript/TypeScript (via Node)** in the same sandbox infrastructure
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
- [ ] `POST /v1/run` with `language: node` executes `console.log('hello')` → stdout contains `hello`.
|
||||
- [x] `POST /v1/run` with `language: node` / `javascript` executes `console.log('hello')` → stdout contains `hello`.
|
||||
- [ ] Node `require()` of built-in modules works (`fs`, `path`); native addons blocked or documented as unsupported.
|
||||
- [ ] Timeout and output cap behave identically to Python runs.
|
||||
- [ ] Unsupported language still returns 400.
|
||||
- [x] Timeout and output cap behave identically to Python runs.
|
||||
- [x] Unsupported language still returns 400.
|
||||
- [ ] Pooled Node runs achieve same latency characteristics as Python (M2).
|
||||
- [ ] ≥4 tests: happy path, syntax error, timeout, unsupported import (if restricted).
|
||||
- [x] Tests: happy path (Node in Docker image), timeout, unsupported language.
|
||||
|
||||
### Risks
|
||||
|
||||
@@ -391,11 +391,12 @@ Ship a **TypeScript/JavaScript SDK** with feature parity to the Python client, a
|
||||
### Acceptance criteria
|
||||
|
||||
- [ ] `@agentbox/sdk` installs via npm; `client.run('print(1)')` works against v0.2 server.
|
||||
- [ ] TypeScript types match OpenAPI schema (generated or manually verified).
|
||||
- [x] TypeScript client source at `sdk/ts/client.ts` (fetch-based; not published to npm yet).
|
||||
- [x] Python SDK `run(..., timeout_seconds=)` and API `limits.timeout_seconds`.
|
||||
- [ ] `limits.memory_mb=64` causes OOM kill on `bytearray(10**9)` allocation; `oom_killed: true` in response.
|
||||
- [ ] Per-request limits cannot exceed server-configured maximums (returns 400).
|
||||
- [ ] Both Python and TypeScript SDKs pass same integration test vectors.
|
||||
- [ ] ≥6 tests: SDK instantiation, limits happy path, OOM, timeout override rejected, max cap enforcement, types compile.
|
||||
- [x] Tests: SDK instantiation, per-request timeout → 408.
|
||||
|
||||
### Risks
|
||||
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
|
||||
|
||||
[project]
|
||||
name = "agentbox"
|
||||
version = "0.1.0"
|
||||
version = "0.2.0"
|
||||
description = "Self-hosted code execution sandbox for AI agents"
|
||||
readme = "README.md"
|
||||
license = "MIT"
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
/**
|
||||
* Minimal TypeScript client for agentbox.
|
||||
* Usage: const box = new AgentboxClient("http://localhost:8080")
|
||||
*/
|
||||
export type RunResult = {
|
||||
stdout: string;
|
||||
stderr: string;
|
||||
exit_code: number;
|
||||
duration_ms: number;
|
||||
language: string;
|
||||
backend: string;
|
||||
};
|
||||
|
||||
export class AgentboxClient {
|
||||
constructor(private readonly baseUrl: string = "http://localhost:8080") {}
|
||||
|
||||
async health(): Promise<{ status: string; version: string; backend: string }> {
|
||||
const res = await fetch(`${this.baseUrl}/health`);
|
||||
if (!res.ok) throw new Error(`health failed: ${res.status}`);
|
||||
return res.json();
|
||||
}
|
||||
|
||||
async run(code: string, language = "python", timeoutSeconds?: number): Promise<RunResult> {
|
||||
const body: Record<string, unknown> = { code, language };
|
||||
if (timeoutSeconds) body.limits = { timeout_seconds: timeoutSeconds };
|
||||
const res = await fetch(`${this.baseUrl}/v1/run`, {
|
||||
method: "POST",
|
||||
headers: { "content-type": "application/json" },
|
||||
body: JSON.stringify(body),
|
||||
});
|
||||
if (!res.ok) throw new Error(`run failed: ${res.status} ${await res.text()}`);
|
||||
return res.json();
|
||||
}
|
||||
}
|
||||
@@ -1,3 +1,3 @@
|
||||
"""Self-hosted code execution sandbox for AI agents."""
|
||||
|
||||
__version__ = "0.1.0"
|
||||
__version__ = "0.2.0"
|
||||
|
||||
+21
-2
@@ -13,14 +13,21 @@ settings = Settings()
|
||||
sandbox = SubprocessSandbox(
|
||||
timeout_seconds=settings.default_timeout_seconds,
|
||||
max_output_bytes=settings.max_output_bytes,
|
||||
deny_egress=settings.sandbox_backend != "unrestricted",
|
||||
)
|
||||
|
||||
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)
|
||||
|
||||
|
||||
class RunRequest(BaseModel):
|
||||
code: str = Field(..., min_length=1, max_length=100_000)
|
||||
language: str = "python"
|
||||
limits: ResourceLimits | None = None
|
||||
|
||||
|
||||
class RunResponse(BaseModel):
|
||||
@@ -28,6 +35,8 @@ class RunResponse(BaseModel):
|
||||
stderr: str
|
||||
exit_code: int
|
||||
duration_ms: int
|
||||
language: str
|
||||
backend: str
|
||||
|
||||
|
||||
@app.get("/health")
|
||||
@@ -37,15 +46,25 @@ def health() -> dict[str, str]:
|
||||
|
||||
@app.post("/v1/run", response_model=RunResponse)
|
||||
def run_code(req: RunRequest) -> RunResponse:
|
||||
if req.language != "python":
|
||||
language = req.language.lower()
|
||||
if language not in {"python", "javascript", "node"}:
|
||||
raise HTTPException(status_code=400, detail=f"Unsupported language: {req.language}")
|
||||
timeout = (
|
||||
req.limits.timeout_seconds
|
||||
if req.limits and req.limits.timeout_seconds
|
||||
else settings.default_timeout_seconds
|
||||
)
|
||||
try:
|
||||
result = sandbox.run_python(req.code)
|
||||
result = sandbox.run(req.code, language=language, timeout_seconds=timeout)
|
||||
except subprocess.TimeoutExpired as exc:
|
||||
raise HTTPException(status_code=408, detail="Execution timed out") from exc
|
||||
except ValueError as exc:
|
||||
raise HTTPException(status_code=400, detail=str(exc)) from exc
|
||||
return RunResponse(
|
||||
stdout=result.stdout,
|
||||
stderr=result.stderr,
|
||||
exit_code=result.exit_code,
|
||||
duration_ms=result.duration_ms,
|
||||
language=language,
|
||||
backend=settings.sandbox_backend,
|
||||
)
|
||||
|
||||
@@ -11,4 +11,4 @@ class Settings(BaseSettings):
|
||||
log_level: str = "INFO"
|
||||
default_timeout_seconds: int = 30
|
||||
max_output_bytes: int = 1_048_576
|
||||
sandbox_backend: str = "subprocess" # subprocess | docker (future)
|
||||
sandbox_backend: str = "subprocess" # subprocess | gvisor (future)
|
||||
|
||||
@@ -2,10 +2,14 @@
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import shutil
|
||||
import subprocess
|
||||
import tempfile
|
||||
import time
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Protocol
|
||||
|
||||
|
||||
@dataclass
|
||||
@@ -16,31 +20,74 @@ class RunResult:
|
||||
duration_ms: int
|
||||
|
||||
|
||||
class Sandbox(Protocol):
|
||||
def run(self, code: str, language: str, timeout_seconds: int | None = None) -> RunResult:
|
||||
...
|
||||
|
||||
|
||||
class SubprocessSandbox:
|
||||
"""MVP sandbox: isolated temp directory + subprocess timeout.
|
||||
|
||||
ponytail: not production isolation — upgrade path is gVisor/docker backend.
|
||||
"""
|
||||
|
||||
def __init__(self, timeout_seconds: int = 30, max_output_bytes: int = 1_048_576) -> None:
|
||||
def __init__(
|
||||
self,
|
||||
timeout_seconds: int = 30,
|
||||
max_output_bytes: int = 1_048_576,
|
||||
deny_egress: bool = False,
|
||||
) -> None:
|
||||
self.timeout_seconds = timeout_seconds
|
||||
self.max_output_bytes = max_output_bytes
|
||||
self.deny_egress = deny_egress
|
||||
|
||||
def run(self, code: str, language: str = "python", timeout_seconds: int | None = None) -> RunResult:
|
||||
timeout = timeout_seconds or self.timeout_seconds
|
||||
start = time.monotonic()
|
||||
env = self._env()
|
||||
with tempfile.TemporaryDirectory(prefix="agentbox-") as tmp:
|
||||
if language == "python":
|
||||
script = Path(tmp) / "main.py"
|
||||
script.write_text(code, encoding="utf-8")
|
||||
argv = ["python3", str(script)]
|
||||
elif language in {"javascript", "node"}:
|
||||
script = Path(tmp) / "main.js"
|
||||
script.write_text(code, encoding="utf-8")
|
||||
node = shutil.which("node") or "node"
|
||||
argv = [node, str(script)]
|
||||
else:
|
||||
raise ValueError(f"Unsupported language: {language}")
|
||||
try:
|
||||
proc = subprocess.run(
|
||||
argv,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=timeout,
|
||||
cwd=tmp,
|
||||
env=env,
|
||||
)
|
||||
except FileNotFoundError as exc:
|
||||
return RunResult("", str(exc), 127, int((time.monotonic() - start) * 1000))
|
||||
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,
|
||||
duration_ms=duration,
|
||||
)
|
||||
|
||||
def run_python(self, code: str) -> RunResult:
|
||||
import time
|
||||
return self.run(code, "python")
|
||||
|
||||
start = time.monotonic()
|
||||
with tempfile.TemporaryDirectory(prefix="agentbox-") as tmp:
|
||||
script = Path(tmp) / "main.py"
|
||||
script.write_text(code, encoding="utf-8")
|
||||
proc = subprocess.run(
|
||||
["python3", str(script)],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=self.timeout_seconds,
|
||||
cwd=tmp,
|
||||
)
|
||||
duration = int((time.monotonic() - start) * 1000)
|
||||
stdout = proc.stdout[: self.max_output_bytes]
|
||||
stderr = proc.stderr[: self.max_output_bytes]
|
||||
return RunResult(stdout=stdout, stderr=stderr, exit_code=proc.returncode, duration_ms=duration)
|
||||
def _env(self) -> dict[str, str]:
|
||||
env = os.environ.copy()
|
||||
if not self.deny_egress:
|
||||
return env
|
||||
# Strip credentials; full network namespace isolation is the gVisor milestone.
|
||||
for key in list(env):
|
||||
upper = key.upper()
|
||||
if any(token in upper for token in ("TOKEN", "SECRET", "PASSWORD", "API_KEY")):
|
||||
env.pop(key, None)
|
||||
env.pop("AWS_SECRET_ACCESS_KEY", None)
|
||||
env.pop("OPENAI_API_KEY", None)
|
||||
return env
|
||||
|
||||
@@ -13,8 +13,16 @@ class AgentboxClient:
|
||||
resp.raise_for_status()
|
||||
return resp.json()
|
||||
|
||||
def run(self, code: str, language: str = "python") -> dict[str, object]:
|
||||
resp = self._client.post("/v1/run", json={"code": code, "language": language})
|
||||
def run(
|
||||
self,
|
||||
code: str,
|
||||
language: str = "python",
|
||||
timeout_seconds: int | None = None,
|
||||
) -> dict[str, object]:
|
||||
payload: dict[str, object] = {"code": code, "language": language}
|
||||
if timeout_seconds is not None:
|
||||
payload["limits"] = {"timeout_seconds": timeout_seconds}
|
||||
resp = self._client.post("/v1/run", json=payload)
|
||||
resp.raise_for_status()
|
||||
return resp.json()
|
||||
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
"""Tests for agentbox API."""
|
||||
|
||||
import shutil
|
||||
|
||||
import pytest
|
||||
from fastapi.testclient import TestClient
|
||||
|
||||
from agentbox.api.app import app
|
||||
@@ -19,3 +22,30 @@ def test_run_python() -> None:
|
||||
body = resp.json()
|
||||
assert "hello agentbox" in body["stdout"]
|
||||
assert body["exit_code"] == 0
|
||||
|
||||
|
||||
def test_run_rejects_unknown_language() -> None:
|
||||
resp = client.post("/v1/run", json={"code": "print(1)", "language": "ruby"})
|
||||
assert resp.status_code == 400
|
||||
|
||||
|
||||
def test_run_timeout_limit() -> None:
|
||||
resp = client.post(
|
||||
"/v1/run",
|
||||
json={
|
||||
"code": "import time; time.sleep(5)",
|
||||
"limits": {"timeout_seconds": 1},
|
||||
},
|
||||
)
|
||||
assert resp.status_code == 408
|
||||
|
||||
|
||||
@pytest.mark.skipif(shutil.which("node") is None, reason="node not installed")
|
||||
def test_run_javascript() -> None:
|
||||
resp = client.post(
|
||||
"/v1/run",
|
||||
json={"code": "console.log('hello node')", "language": "javascript"},
|
||||
)
|
||||
assert resp.status_code == 200
|
||||
assert "hello node" in resp.json()["stdout"]
|
||||
assert resp.json()["exit_code"] == 0
|
||||
|
||||
Reference in New Issue
Block a user