Sandbox

import "github.com/declaw-ai/declaw-go"

Sandbox is the central type. Every instance exposes .Commands, .Files, and .PTY sub-objects for interacting with the sandbox.

Package-level functions

`declaw.Create()`

Create a new sandbox and return a connected *Sandbox.

sbx, err := declaw.Create(ctx,
    declaw.WithTemplate("python"),
    declaw.WithTimeout(300),
    declaw.WithEnvs(map[string]string{"MY_VAR": "hello"}),
)

string

default:"'base'"

Template ID or alias to boot. Defaults to "base" (Ubuntu 22.04).

int

default:"300"

Sandbox lifetime in seconds. The sandbox is killed automatically when the timeout expires unless WithLifecycle sets OnTimeout to "pause".

map[string]string

Arbitrary key-value pairs attached to the sandbox.

map[string]string

Environment variables injected into the sandbox at boot time.

bool

default:"server default (typically true)"

Whether to enable the security proxy. When not specified, the server applies its default. Set to false only for trusted workloads where TLS interception overhead is unacceptable.

SandboxNetworkOpts

Fine-grained network configuration. See SandboxNetworkOpts below.

SecurityPolicy

Full security policy including PII detection, injection defense, transformations, audit, and env masking. See SecurityPolicy.

SandboxLifecycle

Controls sandbox behaviour on timeout. See SandboxLifecycle.

[]VolumeAttachment

Persistent volumes to attach at boot. See Volumes.

Returns (*Sandbox, error)

`declaw.Connect()`

Connect to an existing sandbox by ID without creating a new one.

sbx, err := declaw.Connect(ctx, "sbx-a1b2c3d4")

string

required

The ID of the sandbox to connect to.

Returns (*Sandbox, error)

`declaw.ListSandboxes()`

List sandboxes with optional filtering and pagination.

page, err := declaw.ListSandboxes(ctx,
    declaw.WithState(declaw.StateLive),
    declaw.WithLimit(20),
)
for _, s := range page.Sandboxes {
    fmt.Println(s.SandboxID, s.State)
}

SandboxState

Filter by state (StateLive, StatePaused, StateKilled).

int

Maximum number of results to return.

int

Offset for pagination.

string

API key override for this call.

string

API URL override for this call.

Returns (*SandboxPage, error)

`declaw.KillSandbox()`

Kill a sandbox by ID.

err := declaw.KillSandbox(ctx, "sbx-a1b2c3d4")

`declaw.KillManySandboxes()`

Kill multiple sandboxes in a single call.

results, err := declaw.KillManySandboxes(ctx, []string{"sbx-1", "sbx-2"})
for _, r := range results {
    if r.Error != nil {
        fmt.Println(r.SandboxID, "error:", r.Error)
    }
}

Returns ([]KillResult, error)

`declaw.Restore()`

Restore a sandbox from a snapshot.

sbx, err := declaw.Restore(ctx, "sbx-a1b2c3d4",
    declaw.WithSnapshotID("snap-xyz"),
)

string

required

The sandbox to restore.

string

Specific snapshot to restore from. If omitted, the most recent snapshot is used.

string

API key override for this call.

string

API URL override for this call.

Returns (*Sandbox, error)

Instance methods

`sbx.Kill()`

Kill and destroy the sandbox.

err := sbx.Kill(ctx)

Returns error

`sbx.IsRunning()`

Check whether the sandbox is currently live.

running, err := sbx.IsRunning(ctx)

Returns (bool, error)

`sbx.SetTimeout()`

Update the sandbox timeout in seconds.

err := sbx.SetTimeout(ctx, 600) // extend to 10 minutes

Returns error

`sbx.GetInfo()`

Fetch current metadata and state.

info, err := sbx.GetInfo(ctx)
fmt.Println(info.State)      // "live"
fmt.Println(info.StartedAt)  // *time.Time

Returns (*SandboxInfo, error)

`sbx.GetMetrics()`

Retrieve CPU, memory, and disk usage metrics.

metrics, err := sbx.GetMetrics(ctx)
fmt.Printf("CPU: %.1f%%, Mem: %.1f MB\n",
    metrics.CPUUsagePercent, metrics.MemoryUsageMB)

Returns (*SandboxMetrics, error)

`sbx.Pause()`

Pause the sandbox, taking a snapshot of its state.

err := sbx.Pause(ctx)

`sbx.Resume()`

Resume a previously paused sandbox.

err := sbx.Resume(ctx)

`sbx.CreateSnapshot()`

Create a snapshot of the sandbox’s current state.

snap, err := sbx.CreateSnapshot(ctx)
fmt.Println(snap.SnapshotID)

Returns (*SnapshotInfo, error)

`sbx.ListSnapshots()`

List all snapshots for this sandbox.

snaps, err := sbx.ListSnapshots(ctx)
for _, s := range snaps {
    fmt.Println(s.SnapshotID, s.CreatedAt)
}

Returns ([]SnapshotInfo, error)

`sbx.DeleteSnapshot()`

Delete a snapshot by ID.

err := sbx.DeleteSnapshot(ctx, "snap-xyz")

`sbx.GetHost()`

Return the URL that reverse-proxies HTTP traffic to the given port inside the sandbox. Requires AllowPublicTraffic to be enabled in the sandbox’s network config (the default).

url := sbx.GetHost(8080)
// https://api.declaw.ai/sandboxes/sbx-.../ports/8080

Parameters: port int Returns: string

`sbx.GetMcpURL()`

Return the URL for an MCP server listening on port 50005 inside the sandbox. Equivalent to sbx.GetHost(50005) + "/mcp".

url := sbx.GetMcpURL()
// https://api.declaw.ai/sandboxes/sbx-.../ports/50005/mcp

Returns: string

Properties

Property	Type	Description
`sbx.ID`	`string`	Unique sandbox identifier
`sbx.Commands`	`*Commands`	Commands sub-object
`sbx.Files`	`*Filesystem`	Filesystem sub-object
`sbx.PTY`	`*PTY`	PTY sub-object

Data models

SandboxInfo

type SandboxInfo struct {
    SandboxID  string
    TemplateID string
    Name       string
    Metadata   map[string]string
    StartedAt  *time.Time
    EndAt      *time.Time
    State      SandboxState
}

SandboxState

const (
    StateLive   SandboxState = "live"
    StatePaused SandboxState = "paused"
    StateKilled SandboxState = "killed"
)

SandboxMetrics

type SandboxMetrics struct {
    Timestamp       time.Time
    CPUUsagePercent float64
    MemoryUsageMB   float64
    DiskUsageMB     float64
}

SandboxLifecycle

type SandboxLifecycle struct {
    OnTimeout  string // "kill" or "pause"
    AutoResume bool
}

SnapshotInfo

type SnapshotInfo struct {
    SnapshotID string
    SandboxID  string
    CreatedAt  *time.Time
}

SandboxNetworkOpts

Lower-level network config used directly in Create(WithNetwork(...)). For security-policy-level network rules, see NetworkPolicy.

type SandboxNetworkOpts struct {
    AllowOut           []string // domain patterns allowed for outbound traffic
    DenyOut            []string // domain patterns denied for outbound traffic
    AllowPublicTraffic *bool    // enable inbound public traffic
    MaskRequestHost    *bool    // mask original request host in proxied requests
}

SandboxPage

type SandboxPage struct {
    Sandboxes []SandboxInfo
    Total     int
}

Python SDK

TypeScript SDK

Go SDK

Package-level functions

`declaw.Create()`

`declaw.Connect()`

`declaw.ListSandboxes()`

`declaw.KillSandbox()`

`declaw.KillManySandboxes()`

`declaw.Restore()`

Instance methods

`sbx.Kill()`

`sbx.IsRunning()`

`sbx.SetTimeout()`

`sbx.GetInfo()`

`sbx.GetMetrics()`

`sbx.Pause()`

`sbx.Resume()`

`sbx.CreateSnapshot()`

`sbx.ListSnapshots()`

`sbx.DeleteSnapshot()`

`sbx.GetHost()`

`sbx.GetMcpURL()`

Properties

Data models

SandboxInfo

SandboxState

SandboxMetrics

SandboxLifecycle

SnapshotInfo

SandboxNetworkOpts

SandboxPage

​Package-level functions

​declaw.Create()

​declaw.Connect()

​declaw.ListSandboxes()

​declaw.KillSandbox()

​declaw.KillManySandboxes()

​declaw.Restore()

​Instance methods

​sbx.Kill()

​sbx.IsRunning()

​sbx.SetTimeout()

​sbx.GetInfo()

​sbx.GetMetrics()

​sbx.Pause()

​sbx.Resume()

​sbx.CreateSnapshot()

​sbx.ListSnapshots()

​sbx.DeleteSnapshot()

​sbx.GetHost()

​sbx.GetMcpURL()

​Properties

​Data models

​SandboxInfo

​SandboxState

​SandboxMetrics

​SandboxLifecycle

​SnapshotInfo

​SandboxNetworkOpts

​SandboxPage

Package-level functions

`declaw.Create()`

`declaw.Connect()`

`declaw.ListSandboxes()`

`declaw.KillSandbox()`

`declaw.KillManySandboxes()`

`declaw.Restore()`

Instance methods

`sbx.Kill()`

`sbx.IsRunning()`

`sbx.SetTimeout()`

`sbx.GetInfo()`

`sbx.GetMetrics()`

`sbx.Pause()`

`sbx.Resume()`

`sbx.CreateSnapshot()`

`sbx.ListSnapshots()`

`sbx.DeleteSnapshot()`

`sbx.GetHost()`

`sbx.GetMcpURL()`

Properties

Data models

SandboxInfo

SandboxState

SandboxMetrics

SandboxLifecycle

SnapshotInfo

SandboxNetworkOpts

SandboxPage