From 3ef07d2fe9bde52978adc1b2e7e98cb54d692aad Mon Sep 17 00:00:00 2001 From: Yash Shah Date: Wed, 19 Aug 2026 01:07:32 +0530 Subject: [PATCH] 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. --- CHANGELOG.md | 11 +++++ README.md | 25 +++++----- docker/Dockerfile | 1 + plans/README.md | 2 +- plans/v0.2-next-phase-roadmap.md | 17 +++---- pyproject.toml | 2 +- sdk/ts/client.ts | 34 ++++++++++++++ src/agentbox/__init__.py | 2 +- src/agentbox/api/app.py | 23 ++++++++- src/agentbox/config.py | 2 +- src/agentbox/sandbox/runner.py | 81 +++++++++++++++++++++++++------- src/agentbox/sdk/client.py | 12 ++++- tests/test_api.py | 30 ++++++++++++ 13 files changed, 197 insertions(+), 45 deletions(-) create mode 100644 sdk/ts/client.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 370151b..c4b86b5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index 49f7002..6752564 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docker/Dockerfile b/docker/Dockerfile index 9815fc4..08fed8f 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -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 ./ diff --git a/plans/README.md b/plans/README.md index 9ce2a45..6645594 100644 --- a/plans/README.md +++ b/plans/README.md @@ -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 | diff --git a/plans/v0.2-next-phase-roadmap.md b/plans/v0.2-next-phase-roadmap.md index 3d757d8..1e91874 100644 --- a/plans/v0.2-next-phase-roadmap.md +++ b/plans/v0.2-next-phase-roadmap.md @@ -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 diff --git a/pyproject.toml b/pyproject.toml index 475a841..629b9de 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" diff --git a/sdk/ts/client.ts b/sdk/ts/client.ts new file mode 100644 index 0000000..635e37a --- /dev/null +++ b/sdk/ts/client.ts @@ -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 { + const body: Record = { 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(); + } +} diff --git a/src/agentbox/__init__.py b/src/agentbox/__init__.py index 4b7e03b..2732e91 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.1.0" +__version__ = "0.2.0" diff --git a/src/agentbox/api/app.py b/src/agentbox/api/app.py index d82a179..5318616 100644 --- a/src/agentbox/api/app.py +++ b/src/agentbox/api/app.py @@ -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, ) diff --git a/src/agentbox/config.py b/src/agentbox/config.py index 62476ee..409169c 100644 --- a/src/agentbox/config.py +++ b/src/agentbox/config.py @@ -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) diff --git a/src/agentbox/sandbox/runner.py b/src/agentbox/sandbox/runner.py index 9d7ef02..aa570a3 100644 --- a/src/agentbox/sandbox/runner.py +++ b/src/agentbox/sandbox/runner.py @@ -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 diff --git a/src/agentbox/sdk/client.py b/src/agentbox/sdk/client.py index 607a0f9..1d11a58 100644 --- a/src/agentbox/sdk/client.py +++ b/src/agentbox/sdk/client.py @@ -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() diff --git a/tests/test_api.py b/tests/test_api.py index 4351465..8d9e89b 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -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