How it Works
Zerobox is a lightweight, cross-platform process sandboxing tool designed to isolate untrusted commands with granular control over file access, network activity, and credential exposure. It operates by default in a restrictive mode, blocking writes, network access, and unnecessary environment variables unless explicitly permitted. This approach minimizes risk by ensuring that only explicitly allowed operations are executed within the sandbox.
The core of Zerobox’s functionality is built upon OpenAI Codex’s sandbox runtime, which provides a secure execution environment. For macOS, it uses Seatbelt (sandbox-exec) as the backend, while Linux relies on Bubblewrap, Seccomp, and kernel namespaces for isolation.
Secrets such as API keys are passed to the sandboxed process as placeholders. The real values are dynamically injected only when the process makes network requests to approved domains. This ensures that sensitive credentials are never exposed within the sandbox itself, reducing the attack surface for credential theft or leakage.
File access is controlled through explicit allowlists or blocklists for read and write operations. By default, writes are denied entirely, and only specified paths are permitted for modifications. Network access is similarly restricted, with outbound traffic allowed only to predefined domains. Environment variables are inherited selectively, with only essential variables like PATH, HOME, and USER passed through by default.
Commands can record changes made to the filesystem during execution, allowing users to inspect modifications or revert them to their pre-execution state.
The tool is distributed as a single binary, eliminating the need for Docker containers or virtual machines. This design choice reduces overhead, with typical performance metrics showing around 10ms latency and approximately 7MB memory usage.
For programmatic integration, Zerobox provides SDKs in Rust, TypeScript, and Python.
Use Cases
Zerobox mitigates these risks by confining the execution environment, allowing users to run untrusted code without exposing their filesystem or network.
This ensures that any unintended modifications are isolated and do not affect the broader system. Similarly, network access can be limited to trusted domains, preventing accidental or malicious external connections.
Zerobox is also valuable for restricting LLM tool calls within larger agent systems. Instead of sandboxing the entire agent process, individual tool invocations can be isolated. This granular approach allows the parent agent to operate normally while ensuring that specific operations—such as API calls or file manipulations—are executed in a controlled environment. Full working examples demonstrate how to integrate Zerobox with frameworks like the Vercel AI SDK or Vercel Workflow for durable, sandboxed steps.
In software development workflows, Zerobox can protect repositories during builds or tests. Zerobox enforces these constraints, preventing accidental writes to unintended locations or unauthorized network activity. Similarly, test suites can be run with no network access, ensuring that external calls—whether intentional or accidental—are blocked and detected.
Zerobox allows these secrets to be passed securely to the sandboxed process, with real values injected only for approved domains. This prevents credential exposure within the sandbox while still enabling legitimate operations. Multiple secrets can be managed simultaneously, each restricted to specific hosts as needed.
Key Features & Capabilities
Zerobox implements a deny-by-default security model, where writes, network access, and environment variables are blocked unless explicitly permitted. This principle reduces the risk of accidental or malicious operations by requiring explicit configuration for any non-default behavior.
File access controls are enforced through allowlists and blocklists for both read and write operations. The --allow-write flag permits writes to specified paths, while --deny-write blocks modifications to sensitive directories. Similarly, --allow-read and --deny-read restrict file reads, ensuring that only authorized data is accessible. By default, all reads are allowed except for explicitly denied paths, balancing usability with security.
Network filtering is achieved through domain-specific allowlists and blocklists. The --allow-net flag enables outbound traffic to specified domains, while --deny-net blocks connections to unauthorized hosts. This granular control prevents unintended network activity, such as data exfiltration or unauthorized API calls.
Credential management is a standout feature of Zerobox. Secrets such as API keys are passed to the sandboxed process as placeholders, with real values injected dynamically by a network proxy. The --secret flag defines a secret and its placeholder, while --secret-host restricts the secret’s use to specific domains. This ensures that sensitive credentials are never visible within the sandbox, even if the process logs or inspects environment variables. Multiple secrets can be managed simultaneously, each with its own host restrictions.
Environment variable handling is similarly precise. By default, only essential variables like PATH, HOME, USER, SHELL, TERM, and LANG are inherited. Additional variables can be allowed or blocked using --allow-env and --deny-env flags. Custom environment variables can also be set directly within the sandbox using the --env flag, providing flexibility for application-specific requirements.
Filesystem snapshotting and restoration are supported through the --snapshot and --restore flags.
This efficiency is achieved through the use of lightweight isolation mechanisms, such as Bubblewrap on Linux and Seatbelt on macOS, rather than heavier alternatives like Docker or virtual machines.
Windows support is planned, leveraging restricted tokens, ACLs, and firewall rules to achieve comparable isolation. The tool is distributed as a single binary, simplifying installation and reducing dependencies. Installation methods include shell scripts, npm, PyPI, Cargo, and direct compilation from source, catering to a wide range of user preferences.
The CLI reference provides detailed documentation for all available flags, including examples of their usage. Flags such as --allow-all grant broad permissions, while --strict-sandbox enforces full isolation, failing if weaker mechanisms are insufficient. Debugging support is available through the --debug flag, which logs sandbox configuration and proxy decisions to stderr.
SDKs for Rust, TypeScript, and Python offer programmatic access to Zerobox’s functionality.