Quickstart

zerobox - Process Sandbox

Overview

zerobox is a lightweight, cross-platform process sandboxing tool with file, network, and credential controls. Run commands safely with granular permissions.

Quick Start

Run command with no writes or network

sc zerobox run command "node -e \"console.log('hello')\""

Allow writes to specific directory

sc zerobox run command --allow-write=. "npm install"

List filesystem snapshots

sc zerobox snapshot list

Passthrough to zerobox CLI

sc zerobox _ <zerobox-args>

Key Features

• File Controls: Allow/deny file and directory writes
• Network Controls: Restrict network access to specific domains
• Credential Management: Pass secrets securely without exposing them to the sandbox
• Snapshot & Restore: Record filesystem changes and undo them
• Environment Control: Control which environment variables are passed
• Cross-Platform: Works on Linux, macOS, and Windows

Installation

cargo install zerobox

Or via package managers:

• npm: npm install -g zerobox
• pip: pip install zerobox
• curl: curl -fsSL https://raw.githubusercontent.com/afshinm/zerobox/main/install.sh | sh

Usage Examples

Basic sandboxing

zerobox -- node script.js

Allow specific directory writes

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

Allow network to specific domain

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

Pass secrets securely

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

Record and restore filesystem changes

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

Notes

• Secrets are passed as placeholders and substituted at the network proxy level
• Use --allow-env to pass all parent environment variables
• Use --deny-env to block specific environment variables
• Snapshots can be inspected and restored later