Sandbox

from declaw import Sandbox

Sandbox is the synchronous entry point for all sandbox operations. Every instance exposes a .commands sub-module for running commands and a .files sub-module for filesystem operations.

Class methods

`Sandbox.create()`

Create a new sandbox and return a connected Sandbox instance.

sbx = Sandbox.create(
    template="base",
    timeout=300,
    envs={"MY_VAR": "hello"},
    api_key="your-api-key",
    domain="104.198.24.180:8080",
)

str | None

default:"'base'"

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

int | None

default:"300"

Sandbox lifetime in seconds. The sandbox is killed automatically when the timeout expires unless lifecycle.on_timeout is set to 'pause'.

dict[str, str] | None

default:"None"

Arbitrary key-value pairs attached to the sandbox. Searchable via Sandbox.list().

dict[str, str] | None

default:"None"

Environment variables injected into the sandbox at boot time.

bool

default:"True"

Whether to enable the edge proxy security proxy. Set to False only for trusted workloads where TLS interception overhead is unacceptable.

bool

default:"True"

When False, all outbound traffic is blocked by adding deny_out: ["0.0.0.0/0"] to the network config. Use network for fine-grained control.

dict | SandboxNetworkOpts | None

default:"None"

Fine-grained network configuration. Overrides allow_internet_access when provided. See SandboxNetworkOpts.

SecurityPolicy | None

default:"None"

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

SandboxLifecycle | None

default:"None"

Controls sandbox behaviour on timeout. See SandboxLifecycle.

str | None

default:"$DECLAW_API_KEY"

API key override for this call.

str | None

default:"$DECLAW_DOMAIN"

Domain override for this call. Supports host:port format.

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns Sandbox

`Sandbox.connect()`

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

sbx = Sandbox.connect(
    sandbox_id="abc123",
    api_key="your-api-key",
    domain="104.198.24.180:8080",
)

str

required

The ID of the sandbox to connect to.

int | None

default:"None"

Optionally update the sandbox timeout on connection.

str | None

default:"$DECLAW_API_KEY"

API key override.

str | None

default:"$DECLAW_DOMAIN"

Domain override.

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns Sandbox

`Sandbox.list()`

List sandboxes with optional filtering and pagination.

result = Sandbox.list(
    query=SandboxQuery(state=[SandboxState.RUNNING]),
    limit=20,
    api_key="your-api-key",
    domain="104.198.24.180:8080",
)
sandboxes = result.get("sandboxes", [])

SandboxQuery | None

default:"None"

Filter by metadata or state. See SandboxQuery.

int | None

default:"None"

Maximum number of results to return.

str | None

default:"None"

Pagination cursor from a previous list() call.

str | None

default:"$DECLAW_API_KEY"

API key override.

str | None

default:"$DECLAW_DOMAIN"

Domain override.

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns dict — raw JSON containing sandboxes list and optional next_token.

Instance methods

`sbx.kill()`

Kill and destroy the sandbox. After this call the sandbox ID becomes invalid.

killed = sbx.kill()

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns bool — True if the sandbox was killed, False if it was already dead.

`sbx.is_running()`

Check whether the sandbox is currently in the running state.

if sbx.is_running():
    print("sandbox is alive")

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns bool

`sbx.set_timeout()`

Update the sandbox timeout. The new timeout is relative to the current time.

sbx.set_timeout(600)  # extend to 10 minutes from now

int

required

New timeout in seconds.

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns None

`sbx.get_info()`

Fetch the current metadata and state of the sandbox.

info = sbx.get_info()
print(info.state)       # SandboxState.RUNNING
print(info.started_at)  # datetime.datetime

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns SandboxInfo

`sbx.get_metrics()`

Retrieve CPU, memory, and disk usage metrics for a time range.

import datetime

metrics = sbx.get_metrics(
    start=datetime.datetime.utcnow() - datetime.timedelta(minutes=5),
    end=datetime.datetime.utcnow(),
)
for m in metrics:
    print(m.cpu_usage_percent, m.memory_usage_mb)

datetime.datetime | None

default:"None"

Start of the time range. Defaults to beginning of sandbox lifetime.

datetime.datetime | None

default:"None"

End of the time range. Defaults to now.

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns list[SandboxMetrics]

`sbx.pause()`

Pause a running sandbox, preserving its in-memory state for later resumption.

sbx.pause()

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns None

`sbx.resume()`

Resume a previously paused sandbox.

sbx.resume()

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns None

`sbx.create_snapshot()`

Create a snapshot of the sandbox. The snapshot can be used as a template ID to boot new sandboxes from a known state.

snap = sbx.create_snapshot()
print(snap.snapshot_id)

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns SnapshotInfo

`sbx.snapshot()`

Create a manual snapshot of this sandbox. Manual snapshots accumulate — every call creates a new persistent checkpoint that survives sbx.kill(). Use Sandbox.restore() or sbx.list_snapshots() to retrieve and fork from them.

snap = sbx.snapshot()
print(snap.snapshot_id)

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns Snapshot

`sbx.list_snapshots()`

List all snapshots (periodic, pause, and manual) for this sandbox, newest first.

for snap in sbx.list_snapshots():
    print(snap.snapshot_id, snap.created_at)

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns list[Snapshot]

`Sandbox.restore()`

Restore a sandbox from a snapshot. The restored sandbox may run on a different worker than the original. Returns a usable Sandbox instance already connected to the restored sandbox.

sbx = Sandbox.restore("sbx-a1b2c3d4", snapshot_id="snap-xyz")
sbx.commands.run("echo restored")

str

required

The sandbox to restore.

str | None

default:"None"

Specific snapshot to restore from. If omitted, the most recent snapshot is used (preference order: pause > periodic > manual).

str | None

default:"$DECLAW_API_KEY"

API key override.

str | None

default:"$DECLAW_DOMAIN"

Domain override.

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns Sandbox

`sbx.get_host()`

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

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

int

required

The port number to proxy to inside the sandbox.

Returns: str — fully qualified HTTPS URL for the port proxy endpoint.

`sbx.get_mcp_url()`

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

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

Returns: str

`sbx.close()`

Close the underlying HTTP client and release connection pool resources. Does not kill the sandbox. Call this when you are done with the object but want the sandbox to keep running.

sbx.close()

Context manager

Sandbox supports the context manager protocol. __exit__ closes the HTTP client but does not kill the sandbox. Call sbx.kill() explicitly inside the block if you want the sandbox destroyed.

with Sandbox.create(api_key="key", domain="host:8080") as sbx:
    result = sbx.commands.run("python3 --version")
    print(result.stdout)
    sbx.kill()

Properties

Property	Type	Description
`sbx.sandbox_id`	`str`	Unique sandbox identifier.
`sbx.commands`	`Commands`	Commands sub-module.
`sbx.files`	`Filesystem`	Filesystem sub-module.
`sbx.pty`	`Pty`	PTY sub-module.

Data models

`SandboxInfo`

@dataclass
class SandboxInfo:
    sandbox_id: str
    template_id: str
    name: str
    metadata: dict[str, str]
    started_at: datetime.datetime | None
    end_at: datetime.datetime | None
    state: SandboxState

`SandboxState`

class SandboxState(str, Enum):
    LIVE     = "live"
    RUNNING  = "running"
    PAUSED   = "paused"
    CREATING = "creating"
    KILLED   = "killed"

`SandboxMetrics`

@dataclass
class SandboxMetrics:
    timestamp: datetime.datetime
    cpu_usage_percent: float
    memory_usage_mb: float
    disk_usage_mb: float

`SandboxQuery`

@dataclass
class SandboxQuery:
    metadata: dict[str, str] | None = None
    state: list[SandboxState] | None = None

`SandboxLifecycle`

@dataclass
class SandboxLifecycle:
    on_timeout: str = "kill"   # "kill" or "pause"
    auto_resume: bool = False

`SnapshotInfo`

@dataclass
class SnapshotInfo:
    snapshot_id: str
    sandbox_id: str
    created_at: datetime.datetime | None

Python SDK

TypeScript SDK

Go SDK

Class methods

`Sandbox.create()`

`Sandbox.connect()`

`Sandbox.list()`

Instance methods

`sbx.kill()`

`sbx.is_running()`

`sbx.set_timeout()`

`sbx.get_info()`

`sbx.get_metrics()`

`sbx.pause()`

`sbx.resume()`

`sbx.create_snapshot()`

`sbx.snapshot()`

`sbx.list_snapshots()`

`Sandbox.restore()`

`sbx.get_host()`

`sbx.get_mcp_url()`

`sbx.close()`

Context manager

Properties

Data models

`SandboxInfo`

`SandboxState`

`SandboxMetrics`

`SandboxQuery`

`SandboxLifecycle`

`SnapshotInfo`

​Class methods

​Sandbox.create()

​Sandbox.connect()

​Sandbox.list()

​Instance methods

​sbx.kill()

​sbx.is_running()

​sbx.set_timeout()

​sbx.get_info()

​sbx.get_metrics()

​sbx.pause()

​sbx.resume()

​sbx.create_snapshot()

​sbx.snapshot()

​sbx.list_snapshots()

​Sandbox.restore()

​sbx.get_host()

​sbx.get_mcp_url()

​sbx.close()

​Context manager

​Properties

​Data models

​SandboxInfo

​SandboxState

​SandboxMetrics

​SandboxQuery

​SandboxLifecycle

​SnapshotInfo

Class methods

`Sandbox.create()`

`Sandbox.connect()`

`Sandbox.list()`

Instance methods

`sbx.kill()`

`sbx.is_running()`

`sbx.set_timeout()`

`sbx.get_info()`

`sbx.get_metrics()`

`sbx.pause()`

`sbx.resume()`

`sbx.create_snapshot()`

`sbx.snapshot()`

`sbx.list_snapshots()`

`Sandbox.restore()`

`sbx.get_host()`

`sbx.get_mcp_url()`

`sbx.close()`

Context manager

Properties

Data models

`SandboxInfo`

`SandboxState`

`SandboxMetrics`

`SandboxQuery`

`SandboxLifecycle`

`SnapshotInfo`