Skip to main content

​
Create

Use either the Python SDK or CLI to create a sandbox. The two examples below are equivalent alternatives; the CLI command does not attach to the Python object above. 
from nullspace import Sandbox

sandbox = Sandbox.create(
    template="base",
    vcpus=2,
    memory_mb=512,
    disk_mb=8192,
    timeout=300,
    cwd="/workspace",
    envs={"APP_ENV": "dev"},
    metadata={"project": "docs"},
    network={"mask_request_host": "localhost:${PORT}"},
)
print(sandbox.id)
sandbox.kill()
disk_mb sets the minimum rootfs size (MB). On cold create the disk is grown to this size before boot. Snapshot-backed templates fix their disk size at build time, so for those set the size with Template.build(..., disk_mb=...) rather than per-create — passing a larger disk_mb than the template’s built-in size is rejected.

​
Create From A Template Warm Pool

Use a template warm pool when many sandboxes should start from the same ready custom template. Pass an explicit pool ID and checkout mode: 
sandbox = Sandbox.create(
    template="team/review-api:stable",
    warm_pool="twp_review_api_small",
    warm_pool_mode="prefer",
    warm_pool_wait_ms=1500,
)
print(sandbox.get_info().warm_pool_checkout)
prefer may cold-fallback, require fails with warm_pool_unavailable, and bypass forces cold create. Snapshot restore, resume, fork, hibernate, and pause do not use template warm-pool checkout.

​
Connect

Use connect when another process created the sandbox or when a previous script handed you a sandbox ID. 
sandbox = Sandbox.connect("sb_...")
print(sandbox.get_info().status)
If the ID points at a paused sandbox alias, connect() resumes the snapshot and returns a running sandbox handle. Use Sandbox.get_info_by_id("sb_...") for a read-only lookup that does not wake paused work.

​
List

page = Sandbox.list(limit=20)
for item in page.items:
    print(item.id, item.status, item.template)

while page.has_next:
    for item in page.next_items():
        print(item.id)
Filter lists by state, template, or metadata: 
from nullspace import SandboxQuery

page = Sandbox.list(
    query=SandboxQuery(template="base", metadata={"project": "docs"}),
    limit=20,
)
Use fields when you only need a compact response: 
rows = Sandbox.list(fields=["id", "status", "template"])
for row in rows:
    print(row["id"], row["status"])
When fields is set, the SDK returns raw dictionaries instead of a SandboxPaginator.

​
Inspect

info = sandbox.get_info()
print(info.id, info.status, info.template)
print(info.metadata)
print(sandbox.is_running())
For read-only inspection without resuming a paused sandbox, call Sandbox.get_info_by_id("sb_..."). For metrics without a handle, use Sandbox.get_metrics_by_id("sb_...").

​
Cleanup

Use a context manager for short-lived tasks: 
with Sandbox.create(template="base") as sandbox:
    print(sandbox.commands.run("echo ready", shell=True).stdout)
For long-lived sessions, call sandbox.kill() or Sandbox.kill_by_id("sb_...") when the work is complete.