Zerobox Python SDK

Python SDK for zerobox. Sandbox any command with file, network, and credential controls.

pip install zerobox

Installing the wheel drops the zerobox CLI into your environment's bin/ and exposes a Python SDK.

For CLI usage, secrets concepts, the full flag reference, performance numbers, and platform support see the main README.

Quick start

from zerobox import Sandbox

sandbox = Sandbox.create({"allow_write": ["/tmp"]})
print(sandbox.sh("echo hello").text())

Commands

Three ways to run a command. Each returns a ShellCommand you terminate with .text(), .json(), or .output().

Shell

name = "world"
sandbox.sh(f"echo hello {name}").text()

Inline Python

data = sandbox.py("import json; print(json.dumps({'sum': 1 + 2}))").json()

Explicit command + args

sandbox.exec("python3", ["-c", "print('hi')"]).text()

Results

data = sandbox.sh("cat data.json").json()
result = sandbox.sh("exit 42").output()
# CommandOutput(code=42, stdout='', stderr='')

Async API

Use AsyncSandbox in async applications so waiting for the sandboxed subprocess does not block the event loop. The command shape is the same as Sandbox, but creation and terminators are awaited.

from zerobox import AsyncSandbox

sandbox = await AsyncSandbox.create({"allow_write": ["/tmp"]})

text = await sandbox.sh("echo hello").text()
data = await sandbox.sh("printf '{\"ok\": true}'").json()
result = await sandbox.exec("python3", ["-c", "print('hi')"]).output()

Async commands accept the same timeout option:

import subprocess

try:
    await sandbox.sh("sleep 60").text(timeout=1.0)
except subprocess.TimeoutExpired:
    print("cancelled")

Error handling

Non-zero exit raises SandboxCommandError:

from zerobox import Sandbox, SandboxCommandError

sandbox = Sandbox.create()
try:
    sandbox.sh("exit 1").text()
except SandboxCommandError as e:
    print(e.code, e.stderr)

Secrets

Pass API keys that the sandboxed process never sees. The proxy substitutes the real value only for approved hosts.

import os
from zerobox import Sandbox

sandbox = Sandbox.create({
    "secrets": {
        "OPENAI_API_KEY": {
            "value": os.environ["OPENAI_API_KEY"],
            "hosts": ["api.openai.com"],
        },
        "GITHUB_TOKEN": {
            "value": os.environ["GITHUB_TOKEN"],
            "hosts": ["api.github.com"],
        },
    },
})

sandbox.sh('curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models').text()

See the main README for how placeholder substitution works.

Snapshots

Record filesystem changes and roll them back automatically:

sandbox = Sandbox.create({
    "allow_write": ["."],
    "restore": True,
})
sandbox.sh("npm install").text()

Record without rolling back:

sandbox = Sandbox.create({
    "allow_write": ["."],
    "snapshot": True,
    "snapshot_exclude": ["node_modules"],
})
sandbox.sh("npm install").text()

Cancellation

Pass a timeout (seconds) to any terminator:

import subprocess
try:
    sandbox.sh("sleep 60").text(timeout=1.0)
except subprocess.TimeoutExpired:
    print("cancelled")

Environment variables

sandbox = Sandbox.create({
    "env": {"NODE_ENV": "production"},
    "allow_env": ["PATH", "HOME"],
    "deny_env": ["AWS_SECRET_ACCESS_KEY"],
})

See the main README for what's inherited by default and the CLI equivalents.

Options

Sandbox.create(options) accepts a SandboxOptions dataclass or a plain dict. All fields are optional.

Unknown dict keys (e.g. accidental allowWrite instead of allow_write) raise TypeError at construction time.

Caveats

Sandbox.py(code) runs whichever python3 is on PATH inside the sandbox. If your active interpreter lives outside the sandbox's readable roots (for example uv-managed Pythons under ~/.local/share/uv/), fall back to:

import sys
sandbox = Sandbox.create({"allow_read": [sys.prefix]})
sandbox.exec(sys.executable, ["-c", "print('hi')"]).text()

Other SDKs

• TypeScript SDK (npm: zerobox)
• Rust SDK (crates.io: zerobox)

License

Apache-2.0