Sandboxes

A sandbox is a sandbox — a fully isolated Linux environment with its own filesystem, process tree, and network namespace. Each sandbox boots in approximately 125 milliseconds and runs until it times out or is explicitly killed.

Sandbox states

Creating and Snapshotting above are transient phases, not values the API returns. Only three states are ever reported in the state field:

State	Description
`live`	Sandbox is active and commands can execute
`paused`	Memory and filesystem state preserved, no CPU consumed
`killed`	Sandbox destroyed and resources freed

Create a sandbox

Python
TypeScript

from declaw import Sandbox

sbx = Sandbox.create(
    api_key="your-key",
    domain="localhost:8080",
)
print(sbx.sandbox_id)  # sbx-abc123
sbx.kill()

import { Sandbox } from '@declaw/sdk';

const sbx = await Sandbox.create({
  apiKey: 'your-key',
  domain: 'localhost:8080',
});
console.log(sbx.sandboxId);
await sbx.kill();

Create with full options

Python
TypeScript

from declaw import Sandbox, SecurityPolicy, PIIConfig, ALL_TRAFFIC, SandboxLifecycle

sbx = Sandbox.create(
    template="base",
    timeout=300,                          # seconds until auto-kill
    envs={"MY_VAR": "value"},
    metadata={"project": "my-agent"},
    network={
        "allow_out": ["*.openai.com"],
        "deny_out": [ALL_TRAFFIC],
    },
    security=SecurityPolicy(
        pii=PIIConfig(enabled=True, types=["ssn", "credit_card", "email"]),
        injection_defense=True,
        audit=True,
    ),
    lifecycle=SandboxLifecycle(
        on_timeout="pause",   # "kill" (default) or "pause"
    ),
)

import { Sandbox, ALL_TRAFFIC } from '@declaw/sdk';

const sbx = await Sandbox.create({
  template: 'base',
  timeout: 300,
  envs: { MY_VAR: 'value' },
  metadata: { project: 'my-agent' },
  network: {
    allowOut: ['*.openai.com'],
    denyOut: [ALL_TRAFFIC],
  },
});

SandboxInfo model

The SandboxInfo object is returned by create(), get(), and list().

Field	Type	Description
`sandbox_id`	`str`	Unique identifier in `sbx-*` format
`template_id`	`str`	Template used to create the sandbox
`name`	`str \| None`	Optional human-readable name
`state`	`SandboxState`	Current state: `live`, `paused`, `killed`
`metadata`	`dict[str, str]`	User-defined key-value labels
`started_at`	`datetime`	When the sandbox started
`end_at`	`datetime \| None`	Scheduled termination time

Inspect a sandbox

Python
TypeScript

info = sbx.get_info()
print(info.state)       # SandboxState.running
print(info.started_at)  # 2024-01-15T10:00:00Z
print(info.end_at)      # 2024-01-15T10:05:00Z

print(sbx.is_running())  # True

const info = await sbx.getInfo();
console.log(info.state);       // 'running'
console.log(info.startedAt);   // Date
console.log(info.endAt);       // Date — scheduled termination

List sandboxes

Python
TypeScript

from declaw import Sandbox, SandboxQuery, SandboxState

# List all running sandboxes
result = Sandbox.list(
    query=SandboxQuery(state=[SandboxState.RUNNING]),
    limit=20,
)
for sbx_info in result.get("sandboxes", []):
    print(sbx_info.sandbox_id, sbx_info.state)

const { sandboxes } = await Sandbox.list({
  query: { state: 'running' },
  limit: 20,
});
for (const info of sandboxes) {
  console.log(info.sandboxId, info.state);
}

Connect to an existing sandbox

Use connect() to reconnect to a running or paused sandbox from a different process or after a restart.

Python
TypeScript

sbx = Sandbox.connect("sbx-abc123")
result = sbx.commands.run("echo still here")
print(result.stdout)

const sbx = await Sandbox.connect('sbx-abc123');
const result = await sbx.commands.run('echo still here');

Extend timeout

Python
TypeScript

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

await sbx.setTimeout(600);

Pause and resume

Pausing a sandbox preserves the full memory state and filesystem. No CPU is consumed while paused. The sandbox can be resumed instantly.

Python
TypeScript

sbx.pause()

# Later — resume by connecting
sbx = Sandbox.connect("sbx-abc123")
result = sbx.commands.run("echo resumed")

await sbx.pause();

// Resume by connecting
const resumed = await Sandbox.connect('sbx-abc123');

SandboxMetrics model

Not available yet. The platform endpoint behind this returns 501 metrics collection not yet implemented, so this call currently fails. The method is part of the SDK surface, but there is no metrics data to retrieve.

Python
TypeScript

metrics_list = sbx.get_metrics()
for m in metrics_list:
    print(m.cpu_usage_percent)   # 12.4
    print(m.memory_usage_mb)     # 128.0
    print(m.disk_usage_mb)       # 45.2
    print(m.timestamp)           # datetime

const metrics = await sbx.getMetrics();
for (const m of metrics) {
  console.log(m.cpuUsagePercent);
  console.log(m.memoryUsageMb);
  console.log(m.diskUsageMb);
}

Field	Type	Description
`timestamp`	`datetime`	When the metrics were sampled
`cpu_usage_percent`	`float`	CPU usage as a percentage of allocated vCPUs
`memory_usage_mb`	`float`	RAM consumed in megabytes
`disk_usage_mb`	`float`	Rootfs space consumed in megabytes

Resource configuration

Resources (vCPUs, memory, disk) are fixed at the template level — they cannot be overridden per sandbox. Sending a resources field in Sandbox.create() is rejected with HTTP 400 "resources field is not supported; set resources at template level". To run with different resource sizing, build or select a template with the desired allocation. See Templates.

Each sandbox receives its own copy-on-write rootfs derived from the template. Template-derived resources are also validated against your account tier on every create — requests exceeding MaxVCPUs, MaxMemoryMB, or MaxStorageGiB return HTTP 403.

Kill a sandbox

Python
TypeScript

# Always clean up in a try/finally block
sbx = Sandbox.create()
try:
    result = sbx.commands.run("python3 my_script.py")
    print(result.stdout)
finally:
    sbx.kill()

const sbx = await Sandbox.create();
try {
  const result = await sbx.commands.run('node script.js');
  console.log(result.stdout);
} finally {
  await sbx.kill();
}

Auto-injected environment variables

Every sandbox receives these environment variables automatically:

Variable	Value	Description
`DECLAW_SANDBOX_ID`	`sbx-abc123`	Unique sandbox identifier
`DECLAW_TEMPLATE_ID`	`tpl-base`	Template the sandbox was created from
`DECLAW_SANDBOX`	`true`	Indicates code is running inside Declaw
`DECLAW_SECURITY_POLICY`	JSON string	Active security policy (for introspection)

Lifecycle configuration

from declaw import Sandbox, SandboxLifecycle

sbx = Sandbox.create(
    timeout=300,
    lifecycle=SandboxLifecycle(
        on_timeout="pause",   # "kill" (default) or "pause"
    ),
)

With on_timeout="pause", the sandbox is paused rather than destroyed when it times out: a pause snapshot is taken and the sandbox stops consuming CPU and memory, exactly as if you had called sbx.pause(). Wake it up with sbx.resume(), which also re-arms the timeout. A pause that fails is retried a few times; if it still fails, the sandbox is killed instead. A paused sandbox is kept until you resume or kill it; its timeout does not run while it is paused. auto_resume is accepted but not yet enforced: a paused sandbox is resumed only by an explicit resume() call.

Maximum runtime per session is 1 hour on the Free tier, 72 hours on Pro and 7 days on Enterprise. Pausing stops the clock; resuming re-arms the sandbox’s timeout.

Getting Started

Core Features

CLI

Security

Platform

Deployment

Architecture

Sandbox states

Create a sandbox

Create with full options

SandboxInfo model

Inspect a sandbox

List sandboxes

Connect to an existing sandbox

Extend timeout

Pause and resume

SandboxMetrics model

Resource configuration

Kill a sandbox

Auto-injected environment variables

Lifecycle configuration

​Sandbox states

​Create a sandbox

​Create with full options

​SandboxInfo model

​Inspect a sandbox

​List sandboxes

​Connect to an existing sandbox

​Extend timeout

​Pause and resume

​SandboxMetrics model

​Resource configuration

​Kill a sandbox

​Auto-injected environment variables

​Lifecycle configuration

Sandbox states

Create a sandbox

Create with full options

SandboxInfo model

Inspect a sandbox

List sandboxes

Connect to an existing sandbox

Extend timeout

Pause and resume

SandboxMetrics model

Resource configuration

Kill a sandbox

Auto-injected environment variables

Lifecycle configuration