agentbox-sandbox 0.4.0__py3-none-any.whl

agentbox/__init__.py

@@ -0,0 +1,3 @@
+"""Self-hosted code execution sandbox for AI agents."""
+
+__version__ = "0.4.0"

agentbox/api/app.py

@@ -0,0 +1,85 @@
+"""FastAPI HTTP API."""
+
+import subprocess
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+
+from agentbox import __version__
+from agentbox.config import Settings
+from agentbox.sandbox.runner import SubprocessSandbox
+
+settings = Settings()
+sandbox = SubprocessSandbox(
+    timeout_seconds=settings.default_timeout_seconds,
+    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__)
+
+
+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):
+    code: str = Field(..., min_length=1, max_length=100_000)
+    language: str = "python"
+    limits: ResourceLimits | None = None
+    snapshot: bool = False
+    snapshot_id: str | None = None
+
+
+class RunResponse(BaseModel):
+    stdout: str
+    stderr: str
+    exit_code: int
+    duration_ms: int
+    language: str
+    backend: str
+    snapshot_id: str | None = None
+
+
+@app.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok", "version": __version__, "backend": settings.sandbox_backend}
+
+
+@app.post("/v1/run", response_model=RunResponse)
+def run_code(req: RunRequest) -> RunResponse:
+    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
+    )
+    memory_mb = req.limits.memory_mb if req.limits else None
+    try:
+        result = sandbox.run(
+            req.code,
+            language=language,
+            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
+    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,
+        snapshot_id=result.snapshot_id,
+    )

agentbox/cli.py

@@ -0,0 +1,35 @@
+"""CLI entry point."""
+
+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."""
+
+
+@main.command("serve")
+@click.option("--host", default=None)
+@click.option("--port", default=None, type=int)
+def serve(host: str | None, port: int | None) -> None:
+    settings = Settings()
+    uvicorn.run(
+        "agentbox.api.app:app",
+        host=host or settings.host,
+        port=port or settings.port,
+        reload=False,
+    )
+
+
+@main.command("health")
+def health_cmd() -> None:
+    click.echo(f"agentbox {__version__} OK")
+
+
+if __name__ == "__main__":
+    main()

agentbox/config.py

@@ -0,0 +1,16 @@
+"""Configuration."""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="AGENTBOX_", env_file=".env", extra="ignore")
+
+    host: str = "0.0.0.0"
+    port: int = 8080
+    log_level: str = "INFO"
+    default_timeout_seconds: int = 30
+    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

agentbox/sandbox/runner.py

@@ -0,0 +1,134 @@
+"""Sandbox execution backends."""
+
+from __future__ import annotations
+
+import os
+import resource
+import shutil
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from agentbox.sandbox.snapshots import restore_snapshot, save_snapshot
+
+
+@dataclass
+class RunResult:
+    stdout: str
+    stderr: str
+    exit_code: int
+    duration_ms: int
+    snapshot_id: str | None = None
+
+
+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 + optional memory cap.
+
+    ponytail: not production isolation — upgrade path is gVisor/docker backend.
+    """
+
+    def __init__(
+        self,
+        timeout_seconds: int = 30,
+        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,
+        code: str,
+        language: str = "python",
+        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:
+            workspace = Path(tmp)
+            if snapshot_id:
+                try:
+                    restore_snapshot(snapshot_id, workspace, self.snapshot_dir)
+                except FileNotFoundError as exc:
+                    raise ValueError(str(exc)) from exc
+            if language == "python":
+                script = workspace / "main.py"
+                script.write_text(code, encoding="utf-8")
+                argv = ["python3", str(script)]
+            elif language in {"javascript", "node"}:
+                script = workspace / "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}")
+            preexec = _memory_preexec(mem) if mem else None
+            try:
+                proc = subprocess.run(
+                    argv,
+                    capture_output=True,
+                    text=True,
+                    timeout=timeout,
+                    cwd=tmp,
+                    env=env,
+                    check=False,
+                    preexec_fn=preexec,
+                )
+            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
+        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,
+            snapshot_id=new_snapshot,
+        )
+
+    def run_python(self, code: str) -> RunResult:
+        return self.run(code, "python")
+
+    def _env(self) -> dict[str, str]:
+        env = os.environ.copy()
+        if not self.deny_egress:
+            return env
+        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
+
+
+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

agentbox/sandbox/snapshots.py

@@ -0,0 +1,30 @@
+"""Workspace snapshot save/restore for stateful agent runs."""
+
+from __future__ import annotations
+
+import tarfile
+import uuid
+from pathlib import Path
+
+
+def save_snapshot(workspace: Path, snapshot_dir: Path) -> str:
+    snapshot_dir.mkdir(parents=True, exist_ok=True)
+    snapshot_id = uuid.uuid4().hex
+    archive = snapshot_dir / f"{snapshot_id}.tar.gz"
+    with tarfile.open(archive, "w:gz") as tar:
+        for path in workspace.rglob("*"):
+            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
+
+
+def restore_snapshot(snapshot_id: str, workspace: Path, snapshot_dir: Path) -> None:
+    archive = snapshot_dir / f"{snapshot_id}.tar.gz"
+    if not archive.exists():
+        raise FileNotFoundError(f"Unknown snapshot: {snapshot_id}")
+    with tarfile.open(archive, "r:gz") as tar:
+        try:
+            tar.extractall(workspace, filter="data")
+        except TypeError:
+            tar.extractall(workspace)

agentbox/sdk/client.py

@@ -0,0 +1,57 @@
+"""Python SDK client."""
+
+from typing import Any, cast
+
+import httpx
+
+
+class AgentboxClient:
+    def __init__(self, base_url: str = "http://localhost:8080") -> None:
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.Client(base_url=self.base_url, timeout=60.0)
+
+    def health(self) -> dict[str, str]:
+        resp = self._client.get("/health")
+        self._raise_for_status(resp)
+        return cast(dict[str, str], resp.json())
+
+    def run(
+        self,
+        code: str,
+        language: str = "python",
+        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:
+            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:
+            payload["snapshot_id"] = snapshot_id
+        resp = self._client.post("/v1/run", json=payload)
+        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}")

agentbox_sandbox-0.4.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.5
+Name: agentbox-sandbox
+Version: 0.4.0
+Summary: Self-hosted code execution sandbox for AI agents
+Project-URL: Homepage, https://github.com/yashshah9/agentbox
+Project-URL: Repository, https://github.com/yashshah9/agentbox
+Project-URL: Issues, https://github.com/yashshah9/agentbox/issues
+Author-email: Yash Shah <yash376351@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.111
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: structlog>=24.1
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentbox
+
+Self-hosted **code execution sandbox** for AI agents — one `docker compose up` gives you an HTTP API for running untrusted code in isolated environments.
+
+[![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.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
+- Credential stripping when the backend is not `unrestricted`
+
+## Architecture
+
+```
+Agent / SDK
+    └── POST /v1/run
+            └── SubprocessSandbox (MVP)
+                    └── (next) gVisor / Docker backend
+```
+
+| Component | Technology | Why |
+|-----------|------------|-----|
+| API | FastAPI | Async-ready, OpenAPI docs, widely adopted |
+| Server | uvicorn | Standard ASGI server |
+| Config | pydantic-settings | Typed env config |
+| Tests | pytest + httpx TestClient | Fast API testing |
+
+## Installation
+
+```bash
+pip install agentbox-sandbox
+pip install -e ".[dev]"
+```
+
+## Usage
+
+### Start server
+
+```bash
+agentbox serve
+# or
+docker compose up agentbox
+```
+
+### Run code
+
+```bash
+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
+
+```python
+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))
+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()
+```
+
+## Docker
+
+```bash
+docker compose up agentbox        # start API on :8080
+docker compose run --rm test    # run unit tests
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `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 |
+
+## Running tests
+
+```bash
+pytest tests/ -v
+```
+
+## Roadmap
+
+- [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)
+
+## License
+
+MIT
+
+## 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)

agentbox_sandbox-0.4.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+agentbox/__init__.py,sha256=C9wcnsFp66q8zF3X6RphAKjn3WWeyuKYHWmVVzyH6qQ,79
+agentbox/cli.py,sha256=6XP3uw0BU5G2Z4DzyqOO5SdCae-uf8LR0HTeKYrJ_mM,733
+agentbox/config.py,sha256=T00q3OOB1IPn22Dpz3UnePjWi0rvBPFuZV1UxeFtOIM,527
+agentbox/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentbox/api/app.py,sha256=YqtF0Jd5rocakzJm72ZgUKRyNx-O2riGxHI0yWEW0rU,2643
+agentbox/sandbox/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentbox/sandbox/runner.py,sha256=LYK6ODx53B6o5yVco9pIkYMRr0tbWrsNuT3SZWEaYXk,4638
+agentbox/sandbox/snapshots.py,sha256=J4G2xprZvFWlDAjUPCYFQC3On60tMF2roAohm56Ldds,1045
+agentbox/sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentbox/sdk/client.py,sha256=6mO8WFMmtWkA4UYBnELznFJgsv75mEmn2HMwzGFht4M,1822
+agentbox_sandbox-0.4.0.dist-info/METADATA,sha256=EmZZn31IqhZufyKsZUgCHoSog-iR3GUMctSpLF5cUe4,5573
+agentbox_sandbox-0.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agentbox_sandbox-0.4.0.dist-info/entry_points.txt,sha256=u_320LVs7Vndr2ti0gFQXhR8o9kkjW0LmNjLzEXLr50,47
+agentbox_sandbox-0.4.0.dist-info/licenses/LICENSE,sha256=_oD5FzhsdoFIbsjVU91FFzguT7fXSNwL-z-dZJxLBzU,1078
+agentbox_sandbox-0.4.0.dist-info/RECORD,,

agentbox_sandbox-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentbox_sandbox-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentbox = agentbox.cli:main

agentbox_sandbox-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentbox contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.