> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Create, connect, kill, inspect, extend timeout, pause, snapshot, and restore sandboxes using the Go SDK.

```go theme={null}
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`.

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

<ParamField body="WithTemplate" type="string" default="'base'">
  Template ID or alias to boot. Defaults to `"base"` (Ubuntu 22.04).
</ParamField>

<ParamField body="WithTimeout" type="int" default="300">
  Sandbox lifetime in seconds. The sandbox is killed automatically when the
  timeout expires unless `WithLifecycle` sets `OnTimeout` to `"pause"`.
</ParamField>

<ParamField body="WithMetadata" type="map[string]string">
  Arbitrary key-value pairs attached to the sandbox.
</ParamField>

<ParamField body="WithEnvs" type="map[string]string">
  Environment variables injected into the sandbox at boot time.
</ParamField>

<ParamField body="WithSecure" type="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.
</ParamField>

<ParamField body="WithNetwork" type="SandboxNetworkOpts">
  Fine-grained network configuration. See [SandboxNetworkOpts](#sandboxnetworkopts) below.
</ParamField>

<ParamField body="WithSecurity" type="SecurityPolicy">
  Full security policy including PII detection, injection defense,
  transformations, audit, and env masking. See
  [SecurityPolicy](/sdks/go/security-policy).
</ParamField>

<ParamField body="WithLifecycle" type="SandboxLifecycle">
  Controls sandbox behaviour on timeout. See [SandboxLifecycle](#sandboxlifecycle).
</ParamField>

<ParamField body="WithVolumes" type="[]VolumeAttachment">
  Persistent volumes to attach at boot. See [Volumes](/sdks/go/volumes).
</ParamField>

**Returns** `(*Sandbox, error)`

***

### `declaw.Connect()`

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

```go theme={null}
sbx, err := declaw.Connect(ctx, "sbx-a1b2c3d4")
```

<ParamField body="sandboxID" type="string" required>
  The ID of the sandbox to connect to.
</ParamField>

**Returns** `(*Sandbox, error)`

***

### `declaw.ListSandboxes()`

List sandboxes with optional filtering and pagination.

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

<ParamField body="WithState" type="SandboxState">
  Filter by state (`StateLive`, `StatePaused`, `StateKilled`).
</ParamField>

<ParamField body="WithLimit" type="int">
  Maximum number of results to return.
</ParamField>

<ParamField body="WithOffset" type="int">
  Offset for pagination.
</ParamField>

<ParamField body="WithListAPIKey" type="string">
  API key override for this call.
</ParamField>

<ParamField body="WithListAPIURL" type="string">
  API URL override for this call.
</ParamField>

**Returns** `(*SandboxPage, error)`

***

### `declaw.KillSandbox()`

Kill a sandbox by ID.

```go theme={null}
err := declaw.KillSandbox(ctx, "sbx-a1b2c3d4")
```

***

### `declaw.KillManySandboxes()`

Kill multiple sandboxes in a single call.

```go theme={null}
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.

```go theme={null}
sbx, err := declaw.Restore(ctx, "sbx-a1b2c3d4",
    declaw.WithSnapshotID("snap-xyz"),
)
```

<ParamField body="sandboxID" type="string" required>
  The sandbox to restore.
</ParamField>

<ParamField body="WithSnapshotID" type="string">
  Specific snapshot to restore from. If omitted, the most recent snapshot is
  used.
</ParamField>

<ParamField body="WithRestoreAPIKey" type="string">
  API key override for this call.
</ParamField>

<ParamField body="WithRestoreAPIURL" type="string">
  API URL override for this call.
</ParamField>

**Returns** `(*Sandbox, error)`

***

## Instance methods

### `sbx.Kill()`

Kill and destroy the sandbox.

```go theme={null}
err := sbx.Kill(ctx)
```

**Returns** `error`

***

### `sbx.IsRunning()`

Check whether the sandbox is currently live.

```go theme={null}
running, err := sbx.IsRunning(ctx)
```

**Returns** `(bool, error)`

***

### `sbx.SetTimeout()`

Update the sandbox timeout in seconds.

```go theme={null}
err := sbx.SetTimeout(ctx, 600) // extend to 10 minutes
```

**Returns** `error`

***

### `sbx.GetInfo()`

Fetch current metadata and state.

```go theme={null}
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.

```go theme={null}
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.

```go theme={null}
err := sbx.Pause(ctx)
```

***

### `sbx.Resume()`

Resume a previously paused sandbox.

```go theme={null}
err := sbx.Resume(ctx)
```

***

### `sbx.CreateSnapshot()`

Create a snapshot of the sandbox's current state.

```go theme={null}
snap, err := sbx.CreateSnapshot(ctx)
fmt.Println(snap.SnapshotID)
```

**Returns** `(*SnapshotInfo, error)`

***

### `sbx.ListSnapshots()`

List all snapshots for this sandbox.

```go theme={null}
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.

```go theme={null}
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).

```go theme={null}
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"`.

```go theme={null}
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

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

### SandboxState

```go theme={null}
const (
    StateLive   SandboxState = "live"
    StatePaused SandboxState = "paused"
    StateKilled SandboxState = "killed"
)
```

### SandboxMetrics

```go theme={null}
type SandboxMetrics struct {
    Timestamp       time.Time
    CPUUsagePercent float64
    MemoryUsageMB   float64
    DiskUsageMB     float64
}
```

### SandboxLifecycle

```go theme={null}
type SandboxLifecycle struct {
    OnTimeout  string // "kill" or "pause"
    AutoResume bool
}
```

### SnapshotInfo

```go theme={null}
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](/sdks/go/security-policy#networkpolicy).

```go theme={null}
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

```go theme={null}
type SandboxPage struct {
    Sandboxes []SandboxInfo
    Total     int
}
```