#Get Started

Sandbox0 provides isolated execution environments for AI Agents with persistent storage, session state maintenance, sub-200ms cold starts, and easy self-hosted deployment.

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 data across sandbox lifecycles with volume storage and snapshots
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:

Layer	Components	Purpose
Control Plane	edge-gateway, scheduler	Multi-cluster routing, tenant management, request forwarding
Data Plane	internal-gateway, manager, storage-proxy, netd	Sandbox lifecycle, process execution, file operations, storage

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

Quickstart#

Get your first sandbox running in minutes.

Prerequisites#

A self-hosted deployment
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#

Set up your credentials. Configure the base URL for your self-hosted deployment:

First, create an API key to use as SANDBOX0_TOKEN:

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

# Create a 30-day admin API key and export it
export SANDBOX0_TOKEN="$(s0 apikey create --name test-apikey --role admin --expires-in 30d --raw)"
export SANDBOX0_BASE_URL="http://localhost:30080"

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

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), // Auto-delete 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)

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