Sandbox - Declaw

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"}),
)

WithTemplate

string

default:"'base'"

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

WithTimeout

int

default:"300"

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

WithMetadata

map[string]string

Arbitrary key-value pairs attached to the sandbox.

WithEnvs

map[string]string

Environment variables injected into the sandbox at boot time.

WithSecure

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.

WithNetwork

SandboxNetworkOpts

Fine-grained network configuration. See SandboxNetworkOpts below.

WithSecurity

SecurityPolicy

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

WithLifecycle

SandboxLifecycle

Controls sandbox behaviour on timeout. See SandboxLifecycle.

WithVolumes

[]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")

sandboxID

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

WithState

SandboxState

Filter by state (StateLive, StatePaused, StateKilled).

WithLimit

int

Maximum number of results to return.

WithOffset

int

Offset for pagination.

WithListAPIKey

string

API key override for this call.

WithListAPIURL

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

sandboxID

string

required

The sandbox to restore.

WithSnapshotID

string

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

WithRestoreAPIKey

string

API key override for this call.

WithRestoreAPIURL

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
}

Documentation Index

​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