Get Started

Sandbox0 provides isolated execution environments for AI agents with a persistent sandbox root filesystem across pause/resume, volume storage for durable and shared data, session state maintenance, and fast warm claims. Sandbox0 Cloud uses https://api.sandbox0.ai for sandboxes, templates, volumes, and credentials.

What is Sandbox0?#

Sandbox0 is an enterprise-grade AI Agent Sandbox platform that enables you to:

• Run code securely in isolated environments with full process control
• Persist sandbox files across pause/resume with rootfs checkpoints tied to the sandbox identity
• Persist durable data beyond one sandbox identity with volume storage, snapshots, and forks
• Control network access with fine-grained policies
• Scale efficiently with template-based sandbox pools and fast cold starts

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 hosts the storage API runtime. On each sandbox node, the active process in the ctld HA pair owns rootfs persistence, volume portals, 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 (Required)#

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:

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: 5m)
      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#

Execute code in your sandbox 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 --stream -- ...

Basic File Operations#

Read and write files in your sandbox:

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))

Next Steps#