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

template

str | None

default:"'base'"

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

timeout

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'.

metadata

dict[str, str] | None

default:"None"

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

envs

dict[str, str] | None

default:"None"

Environment variables injected into the sandbox at boot time.

secure

bool

default:"True"

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

allow_internet_access

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.

network

dict | SandboxNetworkOpts | None

default:"None"

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

security

SecurityPolicy | None

default:"None"

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

resources

dict | None

default:"None"

Resource constraints passed directly to the orchestrator (e.g. {"cpu": 2, "memory_mb": 2048}).

lifecycle

SandboxLifecycle | None

default:"None"

Controls sandbox behaviour on timeout. See SandboxLifecycle.

api_key

str | None

default:"$DECLAW_API_KEY"

API key override for this call.

domain

str | None

default:"$DECLAW_DOMAIN"

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

request_timeout

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

sandbox_id

str

required

The ID of the sandbox to connect to.

timeout

int | None

default:"None"

Optionally update the sandbox timeout on connection.

api_key

str | None

default:"$DECLAW_API_KEY"

API key override.

domain

str | None

default:"$DECLAW_DOMAIN"

Domain override.

request_timeout

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

query

SandboxQuery | None

default:"None"

Filter by metadata or state. See SandboxQuery.

limit

int | None

default:"None"

Maximum number of results to return.

next_token

str | None

default:"None"

Pagination cursor from a previous list() call.

api_key

str | None

default:"$DECLAW_API_KEY"

API key override.

domain

str | None

default:"$DECLAW_DOMAIN"

Domain override.

request_timeout

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

request_timeout

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

request_timeout

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

timeout

int

required

New timeout in seconds.

request_timeout

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

request_timeout

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)

start

datetime.datetime | None

default:"None"

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

end

datetime.datetime | None

default:"None"

End of the time range. Defaults to now.

request_timeout

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

request_timeout

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns None

`sbx.resume()`

Resume a previously paused sandbox.

sbx.resume()

request_timeout

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)

request_timeout

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)

request_timeout

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)

request_timeout

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

sandbox_id

str

required

The sandbox to restore.

snapshot_id

str | None

default:"None"

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

api_key

str | None

default:"$DECLAW_API_KEY"

API key override.

domain

str | None

default:"$DECLAW_DOMAIN"

Domain override.

request_timeout

float | None

default:"None"

Per-request HTTP timeout in seconds.

Returns Sandbox

`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

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.close()`

Context manager

Properties

Data models

`SandboxInfo`

`SandboxState`

`SandboxMetrics`

`SandboxQuery`

`SandboxLifecycle`

`SnapshotInfo`

Python SDK

TypeScript 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.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.close()`

Context manager

Properties

Data models

`SandboxInfo`

`SandboxState`

`SandboxMetrics`

`SandboxQuery`

`SandboxLifecycle`

`SnapshotInfo`