airlock-sandbox 0.1.0__tar.gz

airlock_sandbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 farvez
+
+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.

airlock_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: airlock-sandbox
+Version: 0.1.0
+Summary: Python SDK for agent-sandbox: isolated, network-controlled code execution for AI agents.
+Author: farvez
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/farvez/agent-sandbox
+Project-URL: Source, https://github.com/farvez/agent-sandbox/tree/main/sdk/python
+Project-URL: Issues, https://github.com/farvez/agent-sandbox/issues
+Keywords: ai,agents,sandbox,code-execution,gvisor,llm,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# airlock-sandbox
+
+Python SDK for [agent-sandbox](https://github.com/farvez/agent-sandbox): run code from
+AI agents in isolated gVisor containers — no network unless you allow it, hard memory,
+CPU, process and disk limits, and every outbound connection logged.
+
+```bash
+pip install airlock-sandbox
+```
+
+No dependencies; Python 3.9+.
+
+## Quick start
+
+```python
+from airlock_sandbox import Sandbox
+
+with Sandbox(api_key="...", base_url="https://sandbox.example.com") as sbx:
+    sbx.files.write("main.py", "print(2 ** 16)")
+    result = sbx.run("python3 main.py")
+    print(result.stdout)      # 65536
+    print(result.exit_code)   # 0
+```
+
+Leaving the `with` block deletes the session and its files. Settings can come from the
+environment instead: `SANDBOX_API_URL`, `SANDBOX_API_KEY`, and `SANDBOX_API_INSECURE=1`
+for a server with a self-signed certificate (or pass `verify="/path/to/ca.pem"`).
+
+## Running commands
+
+```python
+result = sbx.run("python3 -m pytest -q", timeout=60)   # 1–60 s
+result.stdout, result.stderr, result.exit_code
+result.ok            # exit code 0, not timed out, not killed
+result.timed_out     # hit the timeout
+result.oom_killed    # killed for exceeding the memory limit
+result.warnings      # e.g. over the disk quota
+result.check()       # raises CommandError unless ok; returns the result
+str(result)          # text form with [STDOUT]/[STDERR]/[EXIT CODE] — handy for an LLM
+```
+
+Each command runs in a fresh container; files in the workspace persist between
+commands, processes do not.
+
+## Internet access (egress)
+
+Sandboxes have no network by default. Ask for specific hosts — they must be allowed by
+your tenant's policy on the server:
+
+```python
+with Sandbox(egress=["pypi"]) as sbx:              # presets: pypi, npm, github, huggingface
+    sbx.run("pip install requests", timeout=60).check()
+    for event in sbx.egress_log():
+        print(event["decision"], event["host"], event.get("reason", ""))
+```
+
+Only HTTPS to the listed hosts works; everything else is refused and logged.
+`sbx.egress_policy()` lists what your tenant may request.
+
+## Use as tools for an LLM agent
+
+```python
+from airlock_sandbox import Sandbox
+from airlock_sandbox.tools import openai_tools, anthropic_tools, handle_tool_call
+
+# OpenAI
+response = client.chat.completions.create(model="gpt-4o-mini", messages=messages, tools=openai_tools())
+for call in response.choices[0].message.tool_calls or []:
+    output = handle_tool_call(sbx, call.function.name, call.function.arguments)
+
+# Anthropic
+response = client.messages.create(model="claude-sonnet-5", max_tokens=2048, messages=messages, tools=anthropic_tools())
+for block in response.content:
+    if block.type == "tool_use":
+        output = handle_tool_call(sbx, block.name, block.input)
+```
+
+Tools: `write_file`, `read_file`, `run_command`. `handle_tool_call` never raises — errors
+come back as text the model can act on — and long output is trimmed to 8,000 characters,
+keeping the beginning and the end.
+
+## Errors
+
+All errors inherit from `SandboxError`:
+
+| Exception | When |
+|-----------|------|
+| `AuthenticationError` | Missing or invalid API key (401) |
+| `PermissionDeniedError` | Path outside the workspace, egress outside your policy, someone else's session (403) |
+| `NotFoundError` | Session doesn't exist or expired (404) |
+| `QuotaExceededError` | Write would exceed the workspace disk quota (413) |
+| `RateLimitError` | Tenant limit hit: sessions, requests/minute or concurrent commands (429); see `.retry_after` |
+| `CapacityError` | Every workspace on the server is in use (503) |
+| `ValidationError` | Invalid request, e.g. unknown template (400/422) |
+| `APIConnectionError` | Server unreachable |
+| `CommandError` | Raised by `CommandResult.check()` |
+
+Rate limits (429) and a full server (503) are retried automatically, honouring the
+server's `Retry-After` (`max_retries=3` by default).
+
+## Account
+
+```python
+sbx.usage()    # {"limits": {...}, "sessions_open": 1, "commands_running": 0, "requests_available": 118}
+sbx.health()
+```
+
+## License
+
+MIT

airlock_sandbox-0.1.0/README.md

@@ -0,0 +1,110 @@
+# airlock-sandbox
+
+Python SDK for [agent-sandbox](https://github.com/farvez/agent-sandbox): run code from
+AI agents in isolated gVisor containers — no network unless you allow it, hard memory,
+CPU, process and disk limits, and every outbound connection logged.
+
+```bash
+pip install airlock-sandbox
+```
+
+No dependencies; Python 3.9+.
+
+## Quick start
+
+```python
+from airlock_sandbox import Sandbox
+
+with Sandbox(api_key="...", base_url="https://sandbox.example.com") as sbx:
+    sbx.files.write("main.py", "print(2 ** 16)")
+    result = sbx.run("python3 main.py")
+    print(result.stdout)      # 65536
+    print(result.exit_code)   # 0
+```
+
+Leaving the `with` block deletes the session and its files. Settings can come from the
+environment instead: `SANDBOX_API_URL`, `SANDBOX_API_KEY`, and `SANDBOX_API_INSECURE=1`
+for a server with a self-signed certificate (or pass `verify="/path/to/ca.pem"`).
+
+## Running commands
+
+```python
+result = sbx.run("python3 -m pytest -q", timeout=60)   # 1–60 s
+result.stdout, result.stderr, result.exit_code
+result.ok            # exit code 0, not timed out, not killed
+result.timed_out     # hit the timeout
+result.oom_killed    # killed for exceeding the memory limit
+result.warnings      # e.g. over the disk quota
+result.check()       # raises CommandError unless ok; returns the result
+str(result)          # text form with [STDOUT]/[STDERR]/[EXIT CODE] — handy for an LLM
+```
+
+Each command runs in a fresh container; files in the workspace persist between
+commands, processes do not.
+
+## Internet access (egress)
+
+Sandboxes have no network by default. Ask for specific hosts — they must be allowed by
+your tenant's policy on the server:
+
+```python
+with Sandbox(egress=["pypi"]) as sbx:              # presets: pypi, npm, github, huggingface
+    sbx.run("pip install requests", timeout=60).check()
+    for event in sbx.egress_log():
+        print(event["decision"], event["host"], event.get("reason", ""))
+```
+
+Only HTTPS to the listed hosts works; everything else is refused and logged.
+`sbx.egress_policy()` lists what your tenant may request.
+
+## Use as tools for an LLM agent
+
+```python
+from airlock_sandbox import Sandbox
+from airlock_sandbox.tools import openai_tools, anthropic_tools, handle_tool_call
+
+# OpenAI
+response = client.chat.completions.create(model="gpt-4o-mini", messages=messages, tools=openai_tools())
+for call in response.choices[0].message.tool_calls or []:
+    output = handle_tool_call(sbx, call.function.name, call.function.arguments)
+
+# Anthropic
+response = client.messages.create(model="claude-sonnet-5", max_tokens=2048, messages=messages, tools=anthropic_tools())
+for block in response.content:
+    if block.type == "tool_use":
+        output = handle_tool_call(sbx, block.name, block.input)
+```
+
+Tools: `write_file`, `read_file`, `run_command`. `handle_tool_call` never raises — errors
+come back as text the model can act on — and long output is trimmed to 8,000 characters,
+keeping the beginning and the end.
+
+## Errors
+
+All errors inherit from `SandboxError`:
+
+| Exception | When |
+|-----------|------|
+| `AuthenticationError` | Missing or invalid API key (401) |
+| `PermissionDeniedError` | Path outside the workspace, egress outside your policy, someone else's session (403) |
+| `NotFoundError` | Session doesn't exist or expired (404) |
+| `QuotaExceededError` | Write would exceed the workspace disk quota (413) |
+| `RateLimitError` | Tenant limit hit: sessions, requests/minute or concurrent commands (429); see `.retry_after` |
+| `CapacityError` | Every workspace on the server is in use (503) |
+| `ValidationError` | Invalid request, e.g. unknown template (400/422) |
+| `APIConnectionError` | Server unreachable |
+| `CommandError` | Raised by `CommandResult.check()` |
+
+Rate limits (429) and a full server (503) are retried automatically, honouring the
+server's `Retry-After` (`max_retries=3` by default).
+
+## Account
+
+```python
+sbx.usage()    # {"limits": {...}, "sessions_open": 1, "commands_running": 0, "requests_available": 118}
+sbx.health()
+```
+
+## License
+
+MIT

airlock_sandbox-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "airlock-sandbox"
+dynamic = ["version"]
+description = "Python SDK for agent-sandbox: isolated, network-controlled code execution for AI agents."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []  # standard library only
+authors = [{ name = "farvez" }]
+keywords = ["ai", "agents", "sandbox", "code-execution", "gvisor", "llm", "tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/farvez/agent-sandbox"
+Source = "https://github.com/farvez/agent-sandbox/tree/main/sdk/python"
+Issues = "https://github.com/farvez/agent-sandbox/issues"
+
+[tool.setuptools.dynamic]
+version = { attr = "airlock_sandbox.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+airlock_sandbox = ["py.typed"]

airlock_sandbox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

airlock_sandbox-0.1.0/src/airlock_sandbox/__init__.py

@@ -0,0 +1,41 @@
+"""Python SDK for agent-sandbox: isolated, network-controlled code execution for AI agents.
+
+    from airlock_sandbox import Sandbox
+
+    with Sandbox(egress=["pypi"]) as sbx:
+        sbx.run("pip install requests", timeout=60).check()
+        sbx.files.write("main.py", "import requests; print(requests.__version__)")
+        print(sbx.run("python3 main.py").stdout)
+"""
+from airlock_sandbox.errors import (
+    APIConnectionError,
+    AuthenticationError,
+    CapacityError,
+    CommandError,
+    NotFoundError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    RateLimitError,
+    SandboxError,
+    ValidationError,
+)
+from airlock_sandbox.sandbox import CommandResult, Files, Sandbox
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Sandbox",
+    "CommandResult",
+    "Files",
+    "SandboxError",
+    "APIConnectionError",
+    "AuthenticationError",
+    "CapacityError",
+    "CommandError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ValidationError",
+    "__version__",
+]

airlock_sandbox-0.1.0/src/airlock_sandbox/_http.py

@@ -0,0 +1,104 @@
+"""Small HTTP client on the standard library, with retries for 429/503 and dropped connections."""
+from __future__ import annotations
+
+import json
+import platform
+import socket
+import ssl
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Optional, Union
+
+from airlock_sandbox.errors import STATUS_ERRORS, APIConnectionError, RateLimitError, SandboxError
+
+IDEMPOTENT = {"GET", "DELETE"}
+
+
+class HTTPClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        verify: Union[bool, str] = True,
+        timeout: float = 90,
+        max_retries: int = 3,
+        max_retry_wait: float = 30,
+        user_agent: str = "",
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.max_retry_wait = max_retry_wait
+        self.user_agent = user_agent or f"airlock-sandbox python/{platform.python_version()}"
+        if verify is False:
+            # For a server without a domain (self-signed certificate). Prefer passing the CA file.
+            self._ssl: Optional[ssl.SSLContext] = ssl._create_unverified_context()
+        elif isinstance(verify, str):
+            self._ssl = ssl.create_default_context(cafile=verify)
+        else:
+            self._ssl = None
+
+    def request(self, method: str, path: str, body: Optional[dict] = None) -> Any:
+        attempt = 0
+        while True:
+            try:
+                return self._send(method, path, body)
+            except SandboxError as err:
+                wait = self._retry_wait(err, method, attempt)
+                if wait is None:
+                    raise
+                attempt += 1
+                time.sleep(wait)
+
+    def _retry_wait(self, err: SandboxError, method: str, attempt: int) -> Optional[float]:
+        """Seconds to wait before retrying, or None to give up."""
+        if attempt >= self.max_retries:
+            return None
+        backoff = min(2 ** attempt, self.max_retry_wait)
+        if isinstance(err, RateLimitError):
+            # Not processed, so safe to retry any method. Honour Retry-After when sent.
+            wait = err.retry_after if err.retry_after is not None else backoff
+            return wait if wait <= self.max_retry_wait else None
+        if err.status == 503:
+            return backoff  # no free workspace yet; nothing was created
+        if isinstance(err, APIConnectionError) and method in IDEMPOTENT:
+            return backoff
+        return None
+
+    def _send(self, method: str, path: str, body: Optional[dict]) -> Any:
+        req = urllib.request.Request(
+            self.base_url + path,
+            data=json.dumps(body).encode() if body is not None else None,
+            headers={
+                "X-API-Key": self.api_key,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": self.user_agent,
+            },
+            method=method,
+        )
+        try:
+            with urllib.request.urlopen(req, context=self._ssl, timeout=self.timeout) as resp:
+                raw = resp.read()
+        except urllib.error.HTTPError as err:
+            raise self._http_error(err) from None
+        except (urllib.error.URLError, socket.timeout, ConnectionError, ssl.SSLError) as err:
+            reason = getattr(err, "reason", err)
+            raise APIConnectionError(f"Could not reach {self.base_url}: {reason}") from None
+        return json.loads(raw) if raw else None
+
+    @staticmethod
+    def _http_error(err: urllib.error.HTTPError) -> SandboxError:
+        try:
+            detail = json.loads(err.read().decode()).get("detail", err.reason)
+        except Exception:
+            detail = err.reason
+        message = detail if isinstance(detail, str) else json.dumps(detail)
+        cls = STATUS_ERRORS.get(err.code, SandboxError)
+        if cls is RateLimitError:
+            header = err.headers.get("Retry-After")
+            return RateLimitError(message, detail=detail, retry_after=int(header) if header and header.isdigit() else None)
+        return cls(message, status=err.code, detail=detail)

airlock_sandbox-0.1.0/src/airlock_sandbox/errors.py

@@ -0,0 +1,72 @@
+"""Exceptions raised by the SDK. All inherit from SandboxError."""
+from __future__ import annotations
+
+from typing import Optional
+
+
+class SandboxError(Exception):
+    """Base class. `status` is the HTTP status when the server answered, else None."""
+
+    def __init__(self, message: str, status: Optional[int] = None, detail: object = None):
+        super().__init__(message)
+        self.status = status
+        self.detail = detail if detail is not None else message
+
+
+class APIConnectionError(SandboxError):
+    """The server could not be reached (DNS, TLS, refused connection, timeout)."""
+
+
+class AuthenticationError(SandboxError):
+    """401: missing or invalid API key."""
+
+
+class PermissionDeniedError(SandboxError, PermissionError):
+    """403: path outside the workspace, egress outside the tenant policy, or another tenant's session."""
+
+
+class NotFoundError(SandboxError):
+    """404: the session doesn't exist or has expired."""
+
+
+class QuotaExceededError(SandboxError):
+    """413: the write would take the workspace past its disk quota."""
+
+
+class ValidationError(SandboxError):
+    """400/422: the request was rejected as invalid (e.g. unknown template, timeout out of range)."""
+
+
+class RateLimitError(SandboxError):
+    """429: a per-tenant limit was hit (sessions, requests per minute, or concurrent commands).
+
+    `retry_after` is the server's suggested wait in seconds, when it sent one.
+    """
+
+    def __init__(self, message: str, status: int = 429, detail: object = None, retry_after: Optional[int] = None):
+        super().__init__(message, status, detail)
+        self.retry_after = retry_after
+
+
+class CapacityError(SandboxError):
+    """503: every workspace on the server is in use."""
+
+
+class CommandError(SandboxError):
+    """Raised by CommandResult.check() when a command failed, timed out or was killed."""
+
+    def __init__(self, message: str, result: "object"):
+        super().__init__(message)
+        self.result = result
+
+
+STATUS_ERRORS = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    413: QuotaExceededError,
+    422: ValidationError,
+    429: RateLimitError,
+    503: CapacityError,
+}

airlock_sandbox-0.1.0/src/airlock_sandbox/sandbox.py

@@ -0,0 +1,248 @@
+"""The Sandbox: one isolated session on an agent-sandbox server."""
+from __future__ import annotations
+
+import os
+import re
+import urllib.parse
+from dataclasses import dataclass, field
+from typing import List, Optional, Union
+
+from airlock_sandbox._http import HTTPClient
+from airlock_sandbox.errors import CommandError, SandboxError
+
+DEFAULT_TEMPLATE = "sandbox-base:latest"
+
+
+@dataclass
+class CommandResult:
+    """What a command did. `output` is the server's text form, handy to hand to an LLM."""
+
+    command: str
+    stdout: str
+    stderr: str
+    exit_code: int
+    timed_out: bool = False
+    oom_killed: bool = False
+    warnings: List[str] = field(default_factory=list)
+    output: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0 and not self.timed_out and not self.oom_killed
+
+    def check(self) -> "CommandResult":
+        """Raises CommandError unless the command succeeded; returns self so it can be chained."""
+        if not self.ok:
+            reason = "timed out" if self.timed_out else "was killed for using too much memory" if self.oom_killed \
+                else f"exited with code {self.exit_code}"
+            raise CommandError(f"Command {self.command!r} {reason}.\n{self.output}", result=self)
+        return self
+
+    def __str__(self) -> str:
+        return self.output
+
+    @classmethod
+    def from_response(cls, data: dict) -> "CommandResult":
+        if "exit_code" in data:
+            return cls(
+                command=data.get("command", ""),
+                stdout=data.get("stdout", ""),
+                stderr=data.get("stderr", ""),
+                exit_code=data["exit_code"],
+                timed_out=data.get("timed_out", False),
+                oom_killed=data.get("oom_killed", False),
+                warnings=list(data.get("warnings", [])),
+                output=data.get("output", ""),
+            )
+        return cls._from_text(data.get("command", ""), data.get("output", ""))
+
+    @classmethod
+    def _from_text(cls, command: str, output: str) -> "CommandResult":
+        """Older servers only return the text form; split it back into its sections."""
+        sections = {"STDOUT": [], "STDERR": []}
+        warnings, exit_code, timed_out, current = [], -1, False, None
+        for line in output.split("\n"):
+            marker = re.match(r"^\[(STDOUT|STDERR|WARNING|TIMEOUT|EXIT CODE)\]:\s?(.*)$", line)
+            if not marker:
+                if current:
+                    sections[current].append(line)
+                continue
+            name, rest = marker.groups()
+            current = name if name in sections else None
+            if name in ("WARNING", "TIMEOUT"):
+                warnings.append(rest)
+                timed_out = timed_out or name == "TIMEOUT"
+            elif name == "EXIT CODE" and re.fullmatch(r"-?\d+", rest.strip()):
+                exit_code = int(rest)
+        stdout = "\n".join(sections["STDOUT"])
+        stderr = "\n".join(sections["STDERR"])
+        return cls(
+            command=command,
+            stdout=stdout + "\n" if stdout else "",
+            stderr=stderr + "\n" if stderr else "",
+            exit_code=exit_code,
+            timed_out=timed_out,
+            oom_killed=any("Memory limit" in w for w in warnings),
+            warnings=warnings,
+            output=output,
+        )
+
+
+class Files:
+    """File operations inside the sandbox workspace (paths are relative to /workspace)."""
+
+    def __init__(self, sandbox: "Sandbox"):
+        self._sandbox = sandbox
+
+    def write(self, path: str, content: str) -> None:
+        self._sandbox._call("POST", "/write", {"path": path, "content": content})
+
+    def read(self, path: str) -> str:
+        """Returns the file's text. Raises FileNotFoundError if it doesn't exist."""
+        content = self._sandbox._call("GET", f"/read?{urllib.parse.urlencode({'path': path})}")["content"]
+        if content == f"Error: File '{path}' does not exist.":
+            raise FileNotFoundError(path)
+        return content
+
+
+def _env_flag(name: str) -> bool:
+    return os.getenv(name, "").strip().lower() in {"1", "true", "yes"}
+
+
+class Sandbox:
+    """An isolated workspace on an agent-sandbox server.
+
+        with Sandbox(egress=["pypi"]) as sbx:
+            sbx.files.write("main.py", "print(2 ** 16)")
+            print(sbx.run("python3 main.py").stdout)
+
+    Connection settings default to SANDBOX_API_URL, SANDBOX_API_KEY and
+    SANDBOX_API_INSECURE=1 (accept a self-signed certificate).
+
+    Args:
+        api_key: tenant API key.
+        base_url: server URL, e.g. "https://sandbox.example.com".
+        egress: hosts or presets ("pypi", "npm", "github", "huggingface") this
+            session may reach over HTTPS. Empty means no network at all.
+        template: container image; must be on the server's allowlist.
+        verify: True (default), False to accept a self-signed certificate, or a
+            path to a CA bundle that signed the server's certificate.
+        timeout: seconds to wait for each HTTP response.
+        max_retries: retries for rate limits (429), full servers (503) and
+            dropped connections on idempotent calls.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        *,
+        egress: Optional[List[str]] = None,
+        template: str = DEFAULT_TEMPLATE,
+        verify: Optional[Union[bool, str]] = None,
+        timeout: float = 90,
+        max_retries: int = 3,
+    ):
+        base_url = base_url or os.getenv("SANDBOX_API_URL")
+        api_key = api_key or os.getenv("SANDBOX_API_KEY")
+        if not base_url or not api_key:
+            raise SandboxError("Set base_url and api_key, or the SANDBOX_API_URL and SANDBOX_API_KEY environment variables.")
+        if verify is None:
+            verify = not _env_flag("SANDBOX_API_INSECURE")
+
+        from airlock_sandbox import __version__  # late import: avoids a cycle
+
+        self._http = HTTPClient(base_url, api_key, verify=verify, timeout=timeout, max_retries=max_retries,
+                                user_agent=f"airlock-sandbox/{__version__}")
+        self.template = template
+        self.requested_egress = list(egress or [])
+        self.files = Files(self)
+        self.session_id: Optional[str] = None
+        self.tenant_id: Optional[str] = None
+        self.egress: List[str] = []
+        self.disk_quota_mb: Optional[int] = None
+
+    @classmethod
+    def create(cls, *args, **kwargs) -> "Sandbox":
+        """Creates and starts a sandbox. Remember to close() it, or use `with Sandbox(...)`."""
+        return cls(*args, **kwargs).start()
+
+    # ------------------------------------------------------------------ lifecycle
+
+    def start(self) -> "Sandbox":
+        if self.session_id:
+            return self
+        data = self._http.request("POST", "/v1/sessions", {"template": self.template, "egress": self.requested_egress})
+        self.session_id = data["session_id"]
+        self.tenant_id = data.get("tenant_id")
+        self.egress = data.get("egress", [])
+        self.disk_quota_mb = data.get("disk_quota_mb")
+        return self
+
+    def close(self) -> None:
+        """Deletes the session and its files. Safe to call more than once."""
+        if not self.session_id:
+            return
+        session_id, self.session_id = self.session_id, None
+        try:
+            self._http.request("DELETE", f"/v1/sessions/{session_id}")
+        except SandboxError as err:
+            if err.status != 404:  # already gone (expired) is fine
+                raise
+
+    def __enter__(self) -> "Sandbox":
+        return self.start()
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    @property
+    def base_url(self) -> str:
+        return self._http.base_url
+
+    def __repr__(self) -> str:
+        state = self.session_id or "not started"
+        return f"<Sandbox {state} tenant={self.tenant_id} egress={self.egress}>"
+
+    # ------------------------------------------------------------------ work
+
+    def run(self, command: str, timeout: int = 15) -> CommandResult:
+        """Runs a shell command in a fresh container (1–60 s timeout). Files persist between runs."""
+        data = self._call("POST", "/exec", {"command": command, "timeout_seconds": timeout})
+        return CommandResult.from_response(data)
+
+    def egress_log(self, limit: int = 200) -> List[dict]:
+        """Every outbound connection this session attempted, allowed or denied."""
+        return self._call("GET", f"/egress?limit={int(limit)}")["events"]
+
+    # ------------------------------------------------------------------ account
+
+    def usage(self) -> dict:
+        """This tenant's limits and current usage."""
+        return self._http.request("GET", "/v1/usage")
+
+    def egress_policy(self) -> List[str]:
+        """Hosts this tenant's sessions may request."""
+        return self._http.request("GET", "/v1/egress/policy")["allowed"]
+
+    def health(self) -> dict:
+        return self._http.request("GET", "/healthz")
+
+    # ------------------------------------------------------------------ agent-loop compatibility
+
+    def read_file(self, path: str) -> str:
+        return self.files.read(path)
+
+    def write_file(self, path: str, content: str) -> str:
+        self.files.write(path, content)
+        return f"Successfully wrote {len(content)} characters to {path}"
+
+    def run_command(self, command: str, timeout_seconds: int = 15) -> str:
+        return self.run(command, timeout=timeout_seconds).output
+
+    # ------------------------------------------------------------------ internals
+
+    def _call(self, method: str, suffix: str, body: Optional[dict] = None):
+        if not self.session_id:
+            raise SandboxError("Sandbox not started: use `with Sandbox(...)` or call start().")
+        return self._http.request(method, f"/v1/sessions/{self.session_id}{suffix}", body)

airlock_sandbox-0.1.0/src/airlock_sandbox/tools.py

@@ -0,0 +1,109 @@
+"""Ready-made tools for LLM agents: read files, write files, run commands — in a sandbox.
+
+    from airlock_sandbox import Sandbox
+    from airlock_sandbox.tools import openai_tools, handle_tool_call
+
+    with Sandbox() as sbx:
+        response = client.chat.completions.create(model=..., messages=..., tools=openai_tools())
+        for call in response.choices[0].message.tool_calls or []:
+            result = handle_tool_call(sbx, call.function.name, call.function.arguments)
+
+`anthropic_tools()` gives the same tools in the Anthropic Messages API format.
+handle_tool_call never raises: errors come back as text the model can act on.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Union
+
+from airlock_sandbox.errors import SandboxError
+
+MAX_TOOL_OUTPUT_CHARS = 8000
+
+TOOLS: List[Dict[str, Any]] = [
+    {
+        "name": "write_file",
+        "description": "Create or overwrite a text file in the sandbox workspace.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Path relative to the workspace, e.g. 'src/main.py'"},
+                "content": {"type": "string", "description": "Full file content"},
+            },
+            "required": ["path", "content"],
+        },
+    },
+    {
+        "name": "read_file",
+        "description": "Read a text file from the sandbox workspace.",
+        "parameters": {
+            "type": "object",
+            "properties": {"path": {"type": "string", "description": "Path relative to the workspace"}},
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "run_command",
+        "description": (
+            "Run a shell command in an isolated Linux sandbox (bash, Python 3.11). Files in the workspace "
+            "persist between commands; processes do not. Returns stdout, stderr and the exit code."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "command": {"type": "string", "description": "Shell command, e.g. 'python3 -m pytest -q'"},
+                "timeout_seconds": {"type": "integer", "description": "1-60, default 15", "minimum": 1, "maximum": 60},
+            },
+            "required": ["command"],
+        },
+    },
+]
+
+
+def openai_tools() -> List[Dict[str, Any]]:
+    """Tool definitions for OpenAI Chat Completions (`tools=`)."""
+    return [{"type": "function", "function": dict(t)} for t in TOOLS]
+
+
+def anthropic_tools() -> List[Dict[str, Any]]:
+    """Tool definitions for the Anthropic Messages API (`tools=`)."""
+    return [{"name": t["name"], "description": t["description"], "input_schema": t["parameters"]} for t in TOOLS]
+
+
+def truncate(text: str, limit: int = MAX_TOOL_OUTPUT_CHARS) -> str:
+    """Keeps the head and the tail; errors and exit codes are usually at the end."""
+    if len(text) <= limit:
+        return text
+    head = limit * 2 // 5
+    tail = limit - head
+    return f"{text[:head]}\n\n... [TRUNCATED: {len(text) - head - tail} characters omitted] ...\n\n{text[-tail:]}"
+
+
+def handle_tool_call(sandbox: Any, name: str, arguments: Union[str, Dict[str, Any], None]) -> str:
+    """Runs one tool call against `sandbox` and returns text for the model. Never raises."""
+    try:
+        args = json.loads(arguments) if isinstance(arguments, str) else dict(arguments or {})
+    except (json.JSONDecodeError, TypeError, ValueError) as err:
+        return f"Error: tool arguments were not valid JSON: {err}"
+    if not isinstance(args, dict):
+        return "Error: tool arguments must be a JSON object."
+
+    try:
+        if name == "write_file":
+            sandbox.files.write(args["path"], args["content"])
+            result = f"Wrote {len(args['content'])} characters to {args['path']}"
+        elif name == "read_file":
+            result = sandbox.files.read(args["path"])
+        elif name == "run_command":
+            result = sandbox.run(args["command"], timeout=int(args.get("timeout_seconds", 15))).output
+        else:
+            return f"Error: unknown tool '{name}'. Available: {[t['name'] for t in TOOLS]}"
+    except KeyError as err:
+        return f"Error: missing required argument {err} for {name}."
+    except FileNotFoundError as err:
+        return f"Error: file not found: {err}"
+    except SandboxError as err:
+        return f"Error from sandbox ({type(err).__name__}): {err}"
+    except Exception as err:  # the model should see the problem, not crash the agent loop
+        return f"Error: {name} failed ({type(err).__name__}): {err}"
+    return truncate(result)

airlock_sandbox-0.1.0/src/airlock_sandbox.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: airlock-sandbox
+Version: 0.1.0
+Summary: Python SDK for agent-sandbox: isolated, network-controlled code execution for AI agents.
+Author: farvez
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/farvez/agent-sandbox
+Project-URL: Source, https://github.com/farvez/agent-sandbox/tree/main/sdk/python
+Project-URL: Issues, https://github.com/farvez/agent-sandbox/issues
+Keywords: ai,agents,sandbox,code-execution,gvisor,llm,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# airlock-sandbox
+
+Python SDK for [agent-sandbox](https://github.com/farvez/agent-sandbox): run code from
+AI agents in isolated gVisor containers — no network unless you allow it, hard memory,
+CPU, process and disk limits, and every outbound connection logged.
+
+```bash
+pip install airlock-sandbox
+```
+
+No dependencies; Python 3.9+.
+
+## Quick start
+
+```python
+from airlock_sandbox import Sandbox
+
+with Sandbox(api_key="...", base_url="https://sandbox.example.com") as sbx:
+    sbx.files.write("main.py", "print(2 ** 16)")
+    result = sbx.run("python3 main.py")
+    print(result.stdout)      # 65536
+    print(result.exit_code)   # 0
+```
+
+Leaving the `with` block deletes the session and its files. Settings can come from the
+environment instead: `SANDBOX_API_URL`, `SANDBOX_API_KEY`, and `SANDBOX_API_INSECURE=1`
+for a server with a self-signed certificate (or pass `verify="/path/to/ca.pem"`).
+
+## Running commands
+
+```python
+result = sbx.run("python3 -m pytest -q", timeout=60)   # 1–60 s
+result.stdout, result.stderr, result.exit_code
+result.ok            # exit code 0, not timed out, not killed
+result.timed_out     # hit the timeout
+result.oom_killed    # killed for exceeding the memory limit
+result.warnings      # e.g. over the disk quota
+result.check()       # raises CommandError unless ok; returns the result
+str(result)          # text form with [STDOUT]/[STDERR]/[EXIT CODE] — handy for an LLM
+```
+
+Each command runs in a fresh container; files in the workspace persist between
+commands, processes do not.
+
+## Internet access (egress)
+
+Sandboxes have no network by default. Ask for specific hosts — they must be allowed by
+your tenant's policy on the server:
+
+```python
+with Sandbox(egress=["pypi"]) as sbx:              # presets: pypi, npm, github, huggingface
+    sbx.run("pip install requests", timeout=60).check()
+    for event in sbx.egress_log():
+        print(event["decision"], event["host"], event.get("reason", ""))
+```
+
+Only HTTPS to the listed hosts works; everything else is refused and logged.
+`sbx.egress_policy()` lists what your tenant may request.
+
+## Use as tools for an LLM agent
+
+```python
+from airlock_sandbox import Sandbox
+from airlock_sandbox.tools import openai_tools, anthropic_tools, handle_tool_call
+
+# OpenAI
+response = client.chat.completions.create(model="gpt-4o-mini", messages=messages, tools=openai_tools())
+for call in response.choices[0].message.tool_calls or []:
+    output = handle_tool_call(sbx, call.function.name, call.function.arguments)
+
+# Anthropic
+response = client.messages.create(model="claude-sonnet-5", max_tokens=2048, messages=messages, tools=anthropic_tools())
+for block in response.content:
+    if block.type == "tool_use":
+        output = handle_tool_call(sbx, block.name, block.input)
+```
+
+Tools: `write_file`, `read_file`, `run_command`. `handle_tool_call` never raises — errors
+come back as text the model can act on — and long output is trimmed to 8,000 characters,
+keeping the beginning and the end.
+
+## Errors
+
+All errors inherit from `SandboxError`:
+
+| Exception | When |
+|-----------|------|
+| `AuthenticationError` | Missing or invalid API key (401) |
+| `PermissionDeniedError` | Path outside the workspace, egress outside your policy, someone else's session (403) |
+| `NotFoundError` | Session doesn't exist or expired (404) |
+| `QuotaExceededError` | Write would exceed the workspace disk quota (413) |
+| `RateLimitError` | Tenant limit hit: sessions, requests/minute or concurrent commands (429); see `.retry_after` |
+| `CapacityError` | Every workspace on the server is in use (503) |
+| `ValidationError` | Invalid request, e.g. unknown template (400/422) |
+| `APIConnectionError` | Server unreachable |
+| `CommandError` | Raised by `CommandResult.check()` |
+
+Rate limits (429) and a full server (503) are retried automatically, honouring the
+server's `Retry-After` (`max_retries=3` by default).
+
+## Account
+
+```python
+sbx.usage()    # {"limits": {...}, "sessions_open": 1, "commands_running": 0, "requests_available": 118}
+sbx.health()
+```
+
+## License
+
+MIT

airlock_sandbox-0.1.0/src/airlock_sandbox.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/airlock_sandbox/__init__.py
+src/airlock_sandbox/_http.py
+src/airlock_sandbox/errors.py
+src/airlock_sandbox/py.typed
+src/airlock_sandbox/sandbox.py
+src/airlock_sandbox/tools.py
+src/airlock_sandbox.egg-info/PKG-INFO
+src/airlock_sandbox.egg-info/SOURCES.txt
+src/airlock_sandbox.egg-info/dependency_links.txt
+src/airlock_sandbox.egg-info/top_level.txt
+tests/test_offline.py

airlock_sandbox-0.1.0/src/airlock_sandbox.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

airlock_sandbox-0.1.0/src/airlock_sandbox.egg-info/top_level.txt

@@ -0,0 +1 @@
+airlock_sandbox

airlock_sandbox-0.1.0/tests/test_offline.py

@@ -0,0 +1,63 @@
+"""SDK checks that need no server — CI runs these against the built wheel on several Python versions."""
+import json
+
+import pytest
+
+import airlock_sandbox
+from airlock_sandbox import (
+    CommandError,
+    CommandResult,
+    RateLimitError,
+    Sandbox,
+    SandboxError,
+)
+from airlock_sandbox.errors import STATUS_ERRORS
+from airlock_sandbox.tools import anthropic_tools, handle_tool_call, openai_tools, truncate
+
+
+def test_version_and_public_api():
+    assert airlock_sandbox.__version__.count(".") == 2
+    for name in airlock_sandbox.__all__:
+        assert hasattr(airlock_sandbox, name), name
+
+
+def test_needs_url_and_key(monkeypatch):
+    monkeypatch.delenv("SANDBOX_API_URL", raising=False)
+    monkeypatch.delenv("SANDBOX_API_KEY", raising=False)
+    with pytest.raises(SandboxError, match="SANDBOX_API_KEY"):
+        Sandbox()
+
+
+def test_status_codes_map_to_exceptions():
+    assert STATUS_ERRORS[429] is RateLimitError
+    assert all(issubclass(cls, SandboxError) for cls in STATUS_ERRORS.values())
+
+
+def test_command_result_from_structured_response():
+    r = CommandResult.from_response({"command": "x", "stdout": "a\n", "stderr": "", "exit_code": 1,
+                                     "timed_out": False, "oom_killed": False, "warnings": [], "output": "..."})
+    assert not r.ok and r.stdout == "a\n"
+    with pytest.raises(CommandError):
+        r.check()
+
+
+def test_command_result_from_text_only_response():
+    r = CommandResult.from_response({"command": "x", "output": "[STDOUT]:\nhi\n[EXIT CODE]: 0"})
+    assert r.ok and r.stdout == "hi\n"
+
+
+def test_tool_schemas_serialise():
+    assert len(openai_tools()) == len(anthropic_tools()) == 3
+    json.dumps(openai_tools())
+    json.dumps(anthropic_tools())
+
+
+def test_tool_errors_are_text_not_exceptions():
+    assert "unknown tool" in handle_tool_call(object(), "nope", {})
+    assert "not valid JSON" in handle_tool_call(object(), "run_command", "{")
+
+
+def test_truncate_keeps_both_ends():
+    text = "start" + "x" * 20_000 + "end"
+    out = truncate(text, 1000)
+    assert out.startswith("start") and out.endswith("end") and "TRUNCATED" in out