Get Started

Sandbox0 provides AI agent sandboxes so you can give 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. On growth-enabled templates, the RootFS expands automatically online while the agent keeps running. Sandbox0 Cloud uses https://api.sandbox0.ai for sandboxes, templates, and credentials.

Always available. Without always-on compute costs. On Sandbox0 Cloud, paused sandboxes incur no compute charges. An idle sandbox that stays running still accrues compute charges. Configure pause policies and supported automatic wake-up paths for your application; resume takes time and requires available capacity.

Sandbox0 Cloud is the supported service. Self-hosting is no longer supported. Bring Your Own Cloud (BYOC) is planned and is not available yet. See Deployment Options.

What is Sandbox0?#

Sandbox0 gives each user's AI agent an isolated cloud computer that enables you to:

• Run code securely in isolated environments with full process control
• Release idle compute between tasks, then resume the same sandbox explicitly or through supported access paths with auto_resume enabled
• Run for as long as needed with ttl=0 and hard_ttl=0, or set your own pause and deletion policies
• Persist the whole writable RootFS across pause/resume with checkpoints tied to the sandbox identity
• Grow RootFS automatically online on growth-enabled templates, within the configured device ceiling, without restarting the agent
• Keep growing workspaces reusable with incremental block-COW checkpoints and demand reads on resume
• Version and fan out durable state with rootfs snapshots, restore, and forks
• Control network access with fine-grained policies
• Scale efficiently with one resource-neutral warm-carrier pool and claim-time CPU/memory leases

Control Plane vs Data Plane#

Sandbox0 follows a control plane / data plane architecture:

Each provider/region (e.g., aws-us-east-1) has an independent data plane and control plane deployment with dedicated PostgreSQL and S3 storage.

manager and regional PostgreSQL own lifecycle, capacity, and RootFS metadata. On each dedicated Nomad node, the active process in the ctld HA pair owns RootFS attachment, dynamic lease cgroups, and the network policy runtime; the standby takes over those responsibilities after promotion.

Quickstart#

Get your first sandbox running in minutes.

Prerequisites#

• A Sandbox0 account
• s0 CLI installed

Install s0 CLI#

macOS and Linux:

bash
curl -fsSL https://raw.githubusercontent.com/sandbox0-ai/s0/main/scripts/install.sh | bash

Windows PowerShell:

powershell
irm https://raw.githubusercontent.com/sandbox0-ai/s0/main/scripts/install.ps1 | iex

Or with Go:

bash
go install github.com/sandbox0-ai/s0/cmd/s0@latest

Manual release archives are available from GitHub Releases. See the s0 README for platform-specific manual install steps.

Install SDK#

go
go get github.com/sandbox0-ai/sdk-go

Authenticate#

For Sandbox0 Cloud, sign in with s0 auth login. That is enough for interactive CLI usage.

If you want to use the SDKs or raw HTTP API, create a team-scoped API key and export it as SANDBOX0_TOKEN:

bash
# Login with your account (stores session in ~/.s0/config.yaml)
s0 auth login

# If the server did not auto-select a team yet:
# s0 team list
# s0 team create --name my-team --home-region <region-id>
# s0 team use <team-id>

# Create a 30-day API key for SDK and automation usage.
export SANDBOX0_TOKEN="$(s0 apikey create --name sdk-quickstart --role developer --expires-in 30d --raw)"
export SANDBOX0_BASE_URL="https://api.sandbox0.ai"

go
import sandbox0 "github.com/sandbox0-ai/sdk-go"
import "os"

client, err := sandbox0.NewClient(
  sandbox0.WithToken(os.Getenv("SANDBOX0_TOKEN")),
  sandbox0.WithBaseURL(os.Getenv("SANDBOX0_BASE_URL")),
)

Claim Your First Sandbox#

Create a sandbox from the default template. The examples explicitly set a 5-minute soft TTL and a 1-hour hard TTL; both default to 0 (disabled). Keep the sandbox until you finish the command and file examples below. In Go, place those examples inside main, before it returns and runs the deferred cleanup.

go
package main

import (
  "context"
  "fmt"
  "log"
  "os"

  sandbox0 "github.com/sandbox0-ai/sdk-go"
)

func main() {
  client, err := sandbox0.NewClient(
      sandbox0.WithToken(os.Getenv("SANDBOX0_TOKEN")),
      sandbox0.WithBaseURL(os.Getenv("SANDBOX0_BASE_URL")),
  )
  if err != nil {
      log.Fatal(err)
  }

  ctx := context.Background()

  // Claim a sandbox from the "default" template
  sandbox, err := client.ClaimSandbox(ctx, "default",
      sandbox0.WithSandboxTTL(300),      // Auto-pause after 5 minutes (default: disabled)
      sandbox0.WithSandboxHardTTL(3600), // Delete sandbox state after 1 hour (optional, 0 disables)
  )
  if err != nil {
      log.Fatal(err)
  }
  fmt.Printf("Sandbox ID: %s\n", sandbox.ID)
  fmt.Printf("Status: %s\n", sandbox.Status)

  // Clean up when done
  defer client.DeleteSandbox(ctx, sandbox.ID)
}

Run Your First Command#

Continue with the sandbox created above. If its soft TTL has elapsed, resume it before executing commands. Execute code using Run (REPL-style, stateful) or Cmd (one-shot command):

go
// Run a REPL-style snippet (stateful; env/vars preserved between calls)
runResult, err := sandbox.Run(ctx, "python", "x = 2")
if err != nil {
  log.Fatal(err)
}
fmt.Print(runResult.OutputRaw)

runResult, err = sandbox.Run(ctx, "python", "print(x)")
if err != nil {
  log.Fatal(err)
}
fmt.Print(runResult.OutputRaw)

// Run a one-shot command (stateless)
cmdResult, err := sandbox.Cmd(ctx, "/bin/sh -c 'echo Hello, Sandbox0!'")
if err != nil {
  log.Fatal(err)
}
fmt.Print(cmdResult.OutputRaw)

Need live command output instead of a final buffered result?

• Go: sandbox.CmdStream(...)
• Python: sandbox.cmd_stream(...)
• TypeScript: sandbox.cmdStream(...)
• CLI: s0 sandbox exec sb_abc123 --stream -- ...

Basic File Operations#

Read and write files in your running sandbox. These examples use /tmp, a runtime-only mount whose contents do not persist across filesystem-only pause/resume. Use a path in the writable RootFS, such as /home, for persistent files.

go
// Write a file
_, err = sandbox.WriteFile(ctx, "/tmp/hello.txt", []byte("Hello from Sandbox0!"))
if err != nil {
  log.Fatal(err)
}

// Read the file back
content, err := sandbox.ReadFile(ctx, "/tmp/hello.txt")
if err != nil {
  log.Fatal(err)
}
fmt.Printf("File content: %s\n", string(content))

Clean Up#

After the command and file examples, delete the sandbox to remove its stored state and release its resources. Go's defer above handles this when main returns; use the following in the other clients:

python
client.sandboxes.delete(sandbox.id)

Next Steps#