Documentation/docs/get-started

#Get Started

Sandbox0 provides isolated execution environments for AI agents with persistent storage, session state maintenance, and fast warm claims. Sandbox0 Cloud uses https://api.sandbox0.ai for sandboxes, templates, volumes, and credentials. Managed Agents uses https://agents.sandbox0.ai.

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	regional-gateway, scheduler	Multi-cluster routing, tenant management, request forwarding
Data Plane	cluster-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 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"

ℹ

If you only use the local s0 CLI interactively, you can stop after s0 auth login. API keys are the standard way to authenticate SDK and HTTP requests.

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

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#

Concepts

Understand the runtime, storage, networking, and control-plane concepts before implementation.

Overview

Learn the sandbox lifecycle and the runtime APIs available to each isolated environment.