Archived on October 16, 2026. This repository preserves the historical Apache-2.0 version of Sandbox0. It is read-only and no longer receives updates, bug fixes, security fixes, issues, or pull requests.
Sandbox0 continues as a closed-source product. The hosted service remains available at sandbox0.ai. Current documentation is at sandbox0.ai/docs/sandbox.
For product support, bug reports, or security reports, email contact@sandbox0.ai. Do not post credentials or customer data in public issues. The CLI and Go, JavaScript/TypeScript, and Python SDKs remain open source.
The code already published here remains available under its existing Apache-2.0 license. That license does not cover subsequent private development. Self-hosting instructions below describe this historical version.
Always available. Without always-on compute costs.
Sandbox0 is an open-source AI agent sandbox runtime for giving every user their own cloud computer. Preserve the whole writable root filesystem, pause idle compute, and resume on demand. System configuration, installed software, dependencies, and user files persist across successful checkpoints.
The RootFS can grow automatically online as it fills, while the agent keeps running. Growth-enabled image imports set the available device ceiling; existing images and snapshots retain their captured geometry. The runtime separates durable storage from compute, with incremental checkpoints and demand reads that avoid copying the entire growing RootFS on every pause and resume. Nomad schedules compute; gVisor isolates each sandbox.
On Sandbox0 Cloud, paused sandboxes incur no compute charges. An idle sandbox that remains running still accrues compute charges.
Sandbox0 Cloud uses https://api.sandbox0.ai for sandboxes, templates,
credentials, and team-scoped API keys.
This documentation describes the archived open-source release. For the current hosted product, use the website documentation and maintained SDKs.
Give each user a sandbox they can return to across tasks and sessions:
- Keep the whole RootFS: retain the same sandbox identity and committed
writable filesystem, including software in
/usr/local, configuration in/etc, and user data under/homeor/workspace. - Grow online: expand the root filesystem automatically on growth-enabled templates, within the configured device ceiling, while the agent keeps running.
- Release idle compute: pause between tasks while the RootFS stays in durable storage. Choose your own pause and deletion policies.
- Resume on demand: resume explicitly, or enable
auto_resumefor supported runtime API, SSH, and restartable service access paths.
Wake-up takes time and requires available capacity. Default pause/resume preserves filesystem state and starts fresh processes. Experimental memory checkpoints can also restore supported process state. See pause and resume for configuration and compatibility requirements.
| Differentiator | What it means |
|---|---|
| The whole writable RootFS persists | Keep system configuration, installed software, dependencies, and user files across successful checkpoints, wherever they live in the RootFS. |
| Automatic online RootFS growth | Growth-enabled templates expand the root filesystem as it fills, within the configured device ceiling, without restarting the agent. Existing images retain their captured geometry. |
| Storage and compute are separated | Writable RootFS generations are application-encrypted and stored in S3-compatible object storage. Compute nodes keep disposable caches, not the durable source of truth. |
| The sandbox lifetime is policy-controlled | ttl and hard_ttl default to 0 (disabled). Pause idle compute and later resume the same sandbox identity, or keep it running. |
| Optional memory checkpoints | Explicit experimental memory: true pause and resume can retain supported processes and memory alongside the writable RootFS. Memory fork creates a paused child that can continue the captured processes. The default pause remains filesystem-only. |
| gVisor isolation | Stock runsc provides a per-sandbox application-kernel boundary on dedicated Nomad client nodes. |
| One resource-neutral warm pool | Warm Nomad carrier allocations are compatible by immutable runtime properties, not CPU or memory size. Claim-time CPU and memory are leased atomically from node capacity. |
| Durable environment reuse | Snapshot, restore, fork, and template-from-sandbox use immutable block-COW RootFS generations rather than republishing mutable workspace state as an image. |
A long-running agent's filesystem grows as it works. That accumulated state should not make every later pause or resume transfer the entire workspace.
- Pause incrementally: publish the writable branch's changes while reusing unchanged blocks from the committed RootFS generation.
- Resume on demand: attach the committed generation on fresh compute and fetch the blocks the workload reads, without downloading the entire RootFS before execution can start.
- Keep the same sandbox: installed tools, dependencies, files, and progress remain available across successful checkpoints and runtime generations.
This removes the full-filesystem copy from the lifecycle path. Actual latency still depends on unpublished writes, metadata, cache state, object-store access, and the workload's read working set. Optional memory checkpoint and restore also depend on the execution-state size.
For image imports, template resources.ephemeralStorage sets the initial XFS
capacity (8Gi by default, with supported values from 300Mi through 1Ti).
Deployments with automatic growth enabled expose a larger sparse device and grow
XFS online while processes continue running. Background incremental publication
and acknowledged WAL rotation keep compute-node caches and write journals bounded
as stored data accumulates; unavailable or slow storage can apply write backpressure.
Existing generations retain their committed geometry. Automatic growth is disabled
by default and requires the operator rollout gates.
Install the s0 CLI:
curl -fsSL https://raw.githubusercontent.com/sandbox0-ai/s0/main/scripts/install.sh | bashWindows PowerShell:
irm https://raw.githubusercontent.com/sandbox0-ai/s0/main/scripts/install.ps1 | iexSign in and create a team-scoped API key:
s0 auth login
# If no team is selected yet:
# s0 team list
# s0 team create --name my-team --home-region <region-id>
# s0 team use <team-id>
export SANDBOX0_TOKEN="$(s0 apikey create --name sdk-quickstart --role developer --expires-in 30d --raw)"SDKs default to https://api.sandbox0.ai. Set SANDBOX0_BASE_URL only for a
self-hosted or private deployment.
# Python 3.9+
pip install sandbox0
# Node.js 18+
npm install sandbox0
# Go 1.25+
go get github.com/sandbox0-ai/sdk-goClaim a sandbox, keep state in a REPL context, and run an isolated command:
import os
from sandbox0 import Client
from sandbox0.apispec.models.sandbox_config import SandboxConfig
client = Client(
token=os.environ["SANDBOX0_TOKEN"],
base_url=os.environ.get("SANDBOX0_BASE_URL", "https://api.sandbox0.ai"),
)
with client.sandboxes.open(
"default",
config=SandboxConfig(ttl=300, hard_ttl=3600),
) as sandbox:
sandbox.run("python", "x = 41")
second = sandbox.run("python", "print(x + 1)")
print(second.output_raw, end="")
result = sandbox.cmd("/bin/sh -c 'pwd && ls -la'")
print(result.output_raw, end="")More examples:
- Sandbox lifecycle and execution
- Templates and the unified warm pool
- RootFS snapshots, restore, and fork
- Filesystem and memory pause/resume
- Network policy
- Credentials and egress auth
- Self-hosted deployment
flowchart LR
api["Regional API"] --> manager["manager"]
manager --> pg[("PostgreSQL")]
manager --> slot["resource-neutral<br/>Nomad carrier"]
manager --> ctld["ctld A/B<br/>node runtime"]
ctld --> lease["dynamic resource lease<br/>cgroup v2"]
slot --> driver["Sandbox0 task driver"]
driver --> runsc["stock runsc + procd"]
runsc <--> ctld
ctld --> rootfs["encrypted block-COW RootFS"]
rootfs --> object[("S3-compatible storage")]
Nomad schedules dedicated Sandbox0 nodes and resource-neutral carrier
allocations. On claim, manager and PostgreSQL atomically select a ready slot
and lease exact node CPU and memory. ctld creates the dynamic cgroup and
prepares RootFS and network state; the task driver then writes the committed
lease into the OCI spec and starts stock runsc.
CPU and memory are deliberately absent from the warm-slot compatibility key. Compatibility classes contain only immutable execution properties such as architecture, runsc version and platform, DirectFS/file-access mode, RootFS format, and security class.
| State | Durable? | Location |
|---|---|---|
| Running processes and memory | Only with explicit memory pause/resume | Retained execution checkpoint tied to the committed RootFS generation |
| External connections | Not guaranteed after memory resume | Clients reconnect to the new runtime allocation |
| Writable RootFS | Yes, after a committed checkpoint | Encrypted regional S3-compatible storage |
| Named RootFS snapshot | Yes | Immutable block-COW generation |
| Lifecycle, capacity leases, policy, and metering producer state | Yes | Regional PostgreSQL |
| Historical metering read model | Rebuildable | ClickHouse projection from the PostgreSQL outbox |
By default, pause checkpoints the writable RootFS and releases runtime compute;
resume starts a new runtime generation for the same sandbox identity. On a
deployment that supports memory checkpoints, explicit memory: true on both
pause and resume also retains and restores supported guest processes, memory,
PIDs, open files, and runtime tmpfs state. The runtime generation still changes,
and clients must reconnect to SSH, streaming, and external TCP connections.
Named RootFS snapshots remain filesystem-only. See
Pause And Resume for the
experimental memory mode and its compatibility requirements.
Memory pause/resume and fork are experimental and require a deployment that supports memory checkpoints. Choose memory on both pause and resume:
s0 sandbox pause <sandbox-id> --memory
s0 sandbox resume <sandbox-id> --memory
# Fork captured execution state into a paused child, then restore the child.
s0 sandbox fork <sandbox-id> --memory --idempotency-key branch-task-001
s0 sandbox resume <child-sandbox-id> --memoryThe API equivalents use memory: true; memory fork also requires a stable
Idempotency-Key. Reuse the same key and request body if the fork is pending or
the connection fails. Pause can return before checkpoint publication and cleanup
finish; use SDK lifecycle wait helpers or inspect sandbox status before resuming.
Forking a running source with memory capture replaces the parent's runtime too;
the parent resumes into a new carrier before the fork completes.
Memory resume prefers a retained image matching the committed RootFS and
compatible runsc, platform, CPU, and workload configuration. Missing or
incompatible memory falls back to the committed RootFS with fresh processes.
If memory restore fails after execution is authorized, physical cleanup must
finish before the filesystem-only replacement starts. This fallback is durable
across manager restarts. resumed: false means fallback is still pending; poll
until the sandbox is running. With auto_resume: true, supported inbound access
uses the same memory-first recovery. Explicit calls without memory: true,
TTL pauses, and billing pauses keep their filesystem-only defaults.
Reconnect SSH, streaming, and external TCP clients after resume; their existing connections are not guaranteed to survive. Named snapshots, snapshot claims, restore, rebase, and template-from-sandbox remain RootFS operations.
Sandbox0 separates region-scoped control services from cluster-scoped data planes. One region may contain several data-plane clusters that share the region's PostgreSQL and S3 authorities.
| Layer | Components | Responsibility |
|---|---|---|
| Region control plane | regional-gateway, optional scheduler |
Identity, routing, template authority, and multi-cluster selection |
| Data-plane control | cluster-gateway, manager, ssh-gateway |
Sandbox APIs, lifecycle, RootFS metadata, and node authority |
| Dedicated Nomad nodes | ctld-a, ctld-b, nomad-driver-sandbox0, stock runsc |
Capacity, cgroups, RootFS, network policy, runtime creation, and terminal proof |
| Sandbox runtime | procd inside runsc |
Commands, REPL contexts, files, services, and events |
| Regional stores | PostgreSQL, S3-compatible object storage, optional ClickHouse | Transactional truth, encrypted RootFS, and metering query projection |
Self-hosting uses direct host services or Nomad service jobs for control
services and direct systemd units for node-local ctld A/B. Start with
deploy/nomad/README.md.
This repository contains the Sandbox0 control services, Nomad task driver, node runtime, public API contract, metering producer, deployment assets, and docs. Billing, pricing, invoices, and payments belong outside this repository.
Related repositories:
- CLI: https://github.com/sandbox0-ai/s0
- Go SDK: https://github.com/sandbox0-ai/sdk-go
- JavaScript/TypeScript SDK: https://github.com/sandbox0-ai/sdk-js
- Python SDK: https://github.com/sandbox0-ai/sdk-py
pkg/apispec/openapi.yaml is the only OpenAPI source of truth. Generated code
and SDK copies must be synchronized from it rather than edited by hand.
- Sandbox0 is a runtime boundary, not an agent framework.
- The default pause/resume mode preserves RootFS state only. Explicit memory pause/resume can retain supported process state; external connections still need to reconnect.
- Production nodes must be dedicated to Sandbox0. Nomad carrier resources cover driver overhead only and are not sandbox CPU or memory limits.
- Production acceptance requires truthful physical capacity, multi-node failure tests, and security gates. Do not report a narrower local run as an eight-way production result.
- Browser and computer-use workloads need templates that include their runtime dependencies.
- Do not hand-edit generated OpenAPI or SDK output.
This archived repository no longer accepts contributions. Send current product feedback and bug reports to contact@sandbox0.ai. Reports should include a minimal reproduction, relevant logs, Sandbox0 version or topology, and whether the deployment is Cloud or self-hosted. Remove API keys, tokens, private endpoints, customer data, and credentials before sharing logs.
Sandbox0 is Apache-2.0 licensed. See LICENSE.
Update Default Template and Update Coding Agent Template check daily at
00:23 UTC and rebuild every three UTC epoch days, with manual dispatch available.
Both native architectures must pass stock-gVisor Docker checks before an
immutable multi-architecture release receipt is published. Automatic builds
refresh upstream package layers; default's fixed Python dependencies remain
reviewed compatibility pins. Coding-agent also refreshes exact npm harness
versions and verifies its browser runtime. The hosted infrastructure consumes
these releases during its daily refresh and promotes ready images to builtin
templates. Existing sandbox RootFS generations are unchanged.