Skip to main content
A sandbox is the runtime boundary in Nullspace. It owns a VM, filesystem, process namespace, network routing, lifecycle state, and optional capabilities such as desktop access or mounted volumes. Most Build workflows start by creating a sandbox and then using commands, files, networking, or lifecycle APIs against that sandbox ID.

​
When To Use Sandboxes

NeedSandbox Pattern
Run untrusted or dependency-heavy codeCreate a short-lived sandbox with a timeout and destroy it after collecting output.
Keep a repo or service warm between requestsUse hibernate, pause, or auto-resume instead of rebuilding state.
Start many sandboxes from one ready custom templateUse a template warm pool with explicit checkout mode.
Branch from a known setupCreate a snapshot or fork a warm sandbox.
Give an agent a workspaceStart from an agent, desktop, code-interpreter, or custom template.
Debug failed workRetain the sandbox and inspect it with commands, PTY, SSH, files, or desktop viewer.

​
Quick Example

The Python SDK and CLI snippets below are alternative control planes. Use one path end-to-end unless you are intentionally passing a sandbox ID between tools. 
from nullspace import Sandbox

with Sandbox.create(template="base", timeout=300) as sandbox:
    result = sandbox.commands.run("python3 --version", shell=True)
    print(sandbox.id, result.stdout.strip())

nullspace sandbox create --template base --timeout 300
nullspace sandbox list

​
Core Model

ConceptWhat It Means
TemplateThe base environment used at create time. Use base for general work or a custom template for repeated setup.
Template warm poolReady capacity for a template. A checkout becomes a normal sandbox and is not recycled.
Sandbox IDThe handle for commands, files, preview URLs, metrics, lifecycle, PTY, and SSH.
Workdir/workspace is the default mutable work tree for repo-style and agent workflows.
TimeoutControls what happens when work is idle or runs too long.
LifecycleSandboxes can be created, paused, hibernated, resumed, forked, snapshotted, and destroyed.

​
Common Tasks

Create, connect, and list

Launch sandboxes, reconnect by ID, and paginate running or paused work.

Lifecycle

Understand create, exec, hibernate, reusable snapshots, fork, and destroy.

Persistence

Pause sandboxes and resume paused state later.

Snapshots

Capture reusable baseline state and spawn independent sandboxes from it.

Auto-resume

Wake paused sandboxes from SDK calls, HTTP, and WebSocket traffic.

Fork

Branch warm state into independent children.

Metrics and timeouts

Inspect resource usage and control timeout behavior.

Preview URLs

Expose HTTP and WebSocket services from inside a sandbox.