Skip to main content
Use nullspace sandbox create to boot a sandbox from a template or reusable snapshot. The command returns the sandbox ID and connection metadata.

​
Create From A Template

nullspace sandbox create --template base
Pass --json when you want the full response: 
nullspace sandbox create --template base --json

​
Use A Template Warm Pool

Pass --warm-pool when a sandbox should try to claim ready capacity from a template warm pool: 
nullspace sandbox create \
  --template team/review-api:stable \
  --warm-pool twp_review_api_small \
  --warm-pool-mode prefer \
  --warm-pool-wait 1500 \
  --json
Use --warm-pool-mode require for latency-sensitive work that should fail with warm_pool_unavailable instead of cold creating when no matching ready instance is available. Use --warm-pool-mode bypass to force a cold create.

​
Working Directory, Environment, And Metadata

nullspace sandbox create \
  --template base \
  --cwd /workspace \
  --env API_MODE=test \
  --env-json '{"TRACE":"1"}' \
  --metadata purpose=quickstart \
  --metadata-json '{"team":"eval"}'
The default mutable workspace for repo-style flows is /workspace, but commands and file APIs can use other absolute paths inside the sandbox.

​
Timeouts And Auto-Resume

nullspace sandbox create \
  --template base \
  --timeout 300 \
  --on-timeout pause \
  --auto-resume
Timeout actions control what happens when a sandbox idles. Prefer --on-timeout pause at create time when the sandbox should hibernate instead of being destroyed, especially with --auto-resume. The lower-level --timeout-action hibernate flag maps directly to the API timeout_action field; use it only when you intentionally need that raw field. For an existing sandbox, use nullspace sandbox timeout set ... --action hibernate.

​
Create From A Snapshot

nullspace sandbox create --snapshot-id snap_123 --timeout 300
Snapshots are reusable baselines. They are different from fork, which branches a running sandbox immediately.

​
Attach Volumes

nullspace sandbox create \
  --template base \
  --volume ref=team-data,mount=/data \
  --volume ref=read-models,mount=/models,ro=true
Use volumes when multiple sandboxes need durable shared files.

​
Networking And Desktop Options

nullspace sandbox create --template base --no-internet-access
nullspace sandbox create --template base --network-json '{"allow_out":["203.0.113.0/24"]}'
nullspace sandbox create --template desktop --resolution 1280x720 --dpi 144 --display :1
allow_out entries are CIDR ranges. Desktop create options are only valid for desktop templates.

​
Idempotent Retries

nullspace sandbox create \
  --template base \
  --idempotency-key setup-run-001
Use an idempotency key when retrying a create request from automation.