Sandbox Lifecycle

What You’ll Learn

Creating a sandbox with metadata and environment variables
Retrieving sandbox info (id, state, template) with get_info() / getInfo()
Checking whether a sandbox is running with is_running() / isRunning()
Verifying that environment variables are set inside the sandbox
Extending the sandbox timeout with set_timeout() / setTimeout()
Killing the sandbox and confirming it stopped

Prerequisites

export DECLAW_API_KEY="your-api-key"
export DECLAW_DOMAIN="your-declaw-instance.example.com:8080"

Code Walkthrough

Python
TypeScript

Create a sandbox with metadata and envs:

from declaw import Sandbox

sbx = Sandbox.create(
    template="base",
    timeout=300,
    metadata={"project": "demo", "env": "test"},
    envs={"MY_VAR": "hello"},
)

Inspect the sandbox with get_info() and check its running state:

info = sbx.get_info()
print(f"  sandbox_id: {info.sandbox_id}")
print(f"  state:      {info.state}")
print(f"  template:   {info.template_id}")

running = sbx.is_running()
assert running, "Sandbox should be running after creation"

Verify environment variables by running a command inside the sandbox:

result = sbx.commands.run("echo $MY_VAR", envs={"MY_VAR": "hello"})
print(f"  MY_VAR = {result.stdout.strip()}")

Extend the timeout and then kill:

sbx.set_timeout(600)
print("  Timeout extended to 600 seconds.")

killed = sbx.kill()
running_after = sbx.is_running()
assert not running_after, "Sandbox should not be running after kill"

Always wrap in try/finally — kill() is idempotent:

try:
    # ... all sandbox work ...
finally:
    sbx.kill()  # safe to call even if already killed

Create a sandbox with metadata and envs:

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

const sbx = await Sandbox.create({
  template: "base",
  timeout: 300,
  metadata: { project: "demo", env: "test" },
  envs: { MY_VAR: "hello" },
});

Inspect the sandbox with getInfo() and check running state:

const info = await sbx.getInfo();
console.log(`  sandbox_id: ${info.sandboxId}`);
console.log(`  state:      ${info.state}`);
console.log(`  template:   ${info.templateId}`);

const running = await sbx.isRunning();
if (!running) throw new Error("Sandbox should be running after creation");

Verify environment variables and extend timeout:

const result = await sbx.commands.run("echo $MY_VAR");
console.log(`  MY_VAR = ${result.stdout.trim()}`);

await sbx.setTimeout(600);
console.log("  Timeout extended to 600 seconds.");

Kill and verify:

const killed = await sbx.kill();
const runningAfter = await sbx.isRunning();
// runningAfter === false

Expected Output

==================================================
Declaw Sandbox Lifecycle Example
==================================================

--- Creating Sandbox ---
Sandbox created: sbx_abc123

--- Getting Sandbox Info ---
  sandbox_id: sbx_abc123
  state:      running
  template:   base

--- Checking if Running ---
  is_running: True

--- Running Command with Environment Variables ---
  MY_VAR = hello

--- Extending Timeout ---
  Timeout extended to 600 seconds.

--- Killing Sandbox ---
  kill returned: True

--- Verifying Sandbox Stopped ---
  is_running: False

==================================================
Done!
==================================================

Hello World Multi-Sandbox Isolation

Getting Started

Built-in Templates

Commands

PTY

OpenAI Agents

Filesystem

Volumes

Network Policies

PII Protection

Security Features

LLM Providers

Framework Integrations

Agent-in-Sandbox

Real-World Patterns

Security Demos

Sandbox Lifecycle

What You’ll Learn

Prerequisites

Code Walkthrough

Expected Output

​What You’ll Learn

​Prerequisites

​Code Walkthrough

​Expected Output

What You’ll Learn

Prerequisites

Code Walkthrough

Expected Output