zerobox

Lightweight, cross-platform process sandboxing powered by OpenAI Codex's sandbox runtime.

• Deny by default: Writes, network, and environment variables are blocked unless you allow them
• Credential injection: Pass API keys that the process never sees. Zerobox injects real values only for approved hosts
• File access control: Allow or deny reads and writes to specific paths
• Network filtering: Allow or deny outbound traffic by domain
• Clean environment: Only essential env vars (PATH, HOME, etc.) are inherited by default
• SDKs for Rust, TypeScript, and Python with a consistent API across languages
• Cross-platform: macOS and Linux. Windows support planned
• Single binary: No Docker, no VMs, ~10ms overhead

Install

Quick start

Run a command with no writes and no network access:

zerobox -- node -e "console.log('hello')"

Allow writes to a specific directory:

zerobox --allow-write=. -- node script.js

Allow network to a specific domain:

zerobox --allow-net=api.openai.com -- node agent.js

Pass a secret to a specific host and the inner process never sees the real value:

zerobox --secret OPENAI_API_KEY=sk-proj-123 --secret-host OPENAI_API_KEY=api.openai.com -- node agent.js

Record filesystem changes and undo them after execution:

zerobox --restore --allow-write=. -- npm install

Or record without restoring, then inspect and undo later:

zerobox --snapshot --allow-write=. -- npm install
zerobox snapshot list
zerobox snapshot diff <session-id>
zerobox snapshot restore <session-id>

For programmatic usage jump to the SDK that matches your stack:

• Rust SDK
• TypeScript SDK
• Python SDK

Architecture

Secrets

Secrets are API keys, tokens, or credentials that should never be visible inside the sandbox. The sandboxed process sees a placeholder in the environment variable and the real value is substituted at the network proxy level only for requested hosts.

sandbox process: echo $OPENAI_API_KEY
  -> ZEROBOX_SECRET_a1b2c3d4e5...  (placeholder)

sandbox process: curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/...
  -> proxy intercepts, replaces placeholder with real key
  -> server receives: Authorization: Bearer sk-proj-123

Pass a secret with --secret and restrict it to a specific domain with --secret-host:

zerobox --secret OPENAI_API_KEY=sk-proj-123 --secret-host OPENAI_API_KEY=api.openai.com -- node app.js

Without --secret-host, the secret is passed to all domains:

zerobox --secret TOKEN=abc123 -- node app.js

Multiple secrets with different hosts:

zerobox \
  --secret OPENAI_API_KEY=sk-proj-123 --secret-host OPENAI_API_KEY=api.openai.com \
  --secret GITHUB_TOKEN=ghp-456 --secret-host GITHUB_TOKEN=api.github.com \
  -- node app.js

Node.js fetch does not respect HTTPS_PROXY by default. When running Node.js inside a sandbox with secrets, make sure to pass the --use-env-proxy argument.

For SDK code examples, see the Rust, TypeScript, or Python README.

Environment variables

By default only essential variables are passed to the sandbox, e.g. PATH, HOME, USER, SHELL, TERM, LANG.

Inherit all parent env vars:

zerobox --allow-env -- node app.js

Inherit specific env vars only:

zerobox --allow-env=PATH,HOME,DATABASE_URL -- node app.js

Block specific env vars:

zerobox --allow-env --deny-env=AWS_SECRET_ACCESS_KEY -- node app.js

Or set explicit variables:

zerobox --env NODE_ENV=production --env DEBUG=false -- node app.js

Examples

Run AI-generated code safely

Run AI-generated code without risking file corruption or data leaks:

zerobox -- python3 /tmp/task.py

Or allow writes only to an output directory:

zerobox --allow-write=/tmp/output -- python3 /tmp/task.py

Restrict LLM tool calls

Each AI tool call can be sandboxed individually. The parent agent process runs normally and only some operations are sandboxed. Full working examples:

• examples/ai-agent-sandboxed wraps the entire agent process with secrets so the API key is never visible
• examples/ai-agent uses the Vercel AI SDK with per-tool sandboxing and secrets
• examples/workflow runs Vercel Workflow with sandboxed durable steps

Protect your repo during builds

Run a build with network access but writes confined to ./dist:

zerobox --allow-write=./dist --allow-net -- npm run build

Run tests with no network and catch accidental external calls:

zerobox --allow-write=/tmp -- npm test

Performance

Sandbox overhead is minimal, typically ~10ms and ~7MB:

Best of 10 runs with warmup on Apple M5 Pro. Run ./bench/run.sh to reproduce.

Platform support

CLI reference

Snapshot subcommands

SDKs

License

Apache-2.0