Skip to main content
Install the optional CLI extras: 
python -m pip install "nullspace-sdk[cli]==0.1.9"

​
Authenticate

Hosted private beta: 
nullspace auth login --api-url https://api.13-215-85-171.sslip.io
nullspace doctor
nullspace quickstart
Self-hosted single-host localhost/no-domain mode: 
export NULLSPACE_API_KEY="$(sudo cat /etc/nullspace/operator-api-key)"
export NULLSPACE_API_URL=http://localhost
nullspace doctor
nullspace sandbox list
Self-hosted owned-domain mode uses the owned Caddy/API origin: 
export NULLSPACE_API_URL=https://nullspace.example
The CLI reads environment variables, project .env, ~/.config/nullspace/config.json, then legacy ~/.nullspace/config.json. SDK constructors also accept explicit api_key= and base_url= arguments. Use NULLSPACE_API_KEY and NULLSPACE_API_URL directly for scripts, CI, and coding agents. The SDK/CLI client variable is NULLSPACE_API_URL; the similarly named VITE_NULLSPACE_API_BASE is only for console builds.

​
Sandboxes

nullspace sandbox create --template base
nullspace sandbox create --template base --on-timeout pause --auto-resume
nullspace sandbox create --snapshot-id snap_123 --timeout 300
nullspace sandbox create --template desktop --resolution 1280x720 --dpi 144
nullspace sandbox list
nullspace sandbox list --state running --metadata team=eval
nullspace sandbox exec sb_123 --shell "echo hello"
nullspace ssh sb_123 -- python --version
nullspace sandbox ssh-access sb_123 --print-command
nullspace sandbox url sb_123 8080
nullspace sandbox preview-url create sb_123 8080 --expires 15m --wait
nullspace sandbox preview-url list sb_123 --port 8080 --json
nullspace sandbox preview-proxy-target create sb_123 8080 --transport http --transport websocket
nullspace sandbox metrics sb_123
nullspace sandbox metrics sb_123 --json
nullspace sandbox kill sb_123
The text form prints CPU, memory, and disk samples. Use --json when another tool should consume the raw metrics payload. For create-time pause/hibernate behavior, prefer --on-timeout pause; use nullspace sandbox timeout set sb_123 --seconds 300 --action hibernate when changing an existing sandbox. Use nullspace ssh when a local tool requires OpenSSH; it mints a short-lived certificate for the Nullspace SSH relay. Use sandbox preview-url for direct preview link lifecycle, inventory, and revocation. Human output redacts signed preview URLs by default; use --raw only for an explicit secret-bearing display action. Grant list output includes safe usage counters and last-error metadata; use --json for automation that needs raw returned values.

​
Files and lifecycle

nullspace sandbox upload sb_123 ./report.txt /workspace/report.txt
nullspace sandbox file list sb_123 /workspace
nullspace sandbox file upload-url sb_123 /workspace/report.txt
nullspace sandbox desktop screenshot sb_123 --output screen.png
nullspace sandbox code run sb_123 "print('hello')" --json
nullspace snapshot create sb_123
nullspace lifecycle events --limit 20
nullspace lifecycle stream --sandbox-id sb_123 --live-only
nullspace monitor stream --include-processes
nullspace lifecycle webhooks deliveries wh_123
nullspace lifecycle webhooks delivery wh_123 del_123

​
Volumes

Volume commands require a shared-volume-enabled environment. 
nullspace volume list
nullspace volume get team-data
nullspace volume ls-files team-data /
printf "hello" | nullspace volume write team-data /hello.txt
nullspace volume read team-data /hello.txt
nullspace volume find team-data /datasets "needle"
nullspace volume upload-url team-data /models/model.bin
nullspace volume download-url team-data /models/model.bin
nullspace volume upload team-data ./model.bin /models/model.bin
nullspace volume download team-data /models/model.bin ./model.bin
nullspace volume delete vol_12345678
They do not make live VM memory or mutable rootfs snapshot state portable; shared volumes remain external durable storage that remounts on compatible resume and fork. Concepts: Create, Destroy. API reference: createSandbox, destroySandbox, createVolume. Use nullspace schema to inspect the installed command tree and generated MCP tool input schemas. Install nullspace-sdk[cli,mcp]==0.1.9 before using nullspace mcp serve so the MCP server dependency is available. For Claude Code or Codex running locally, run nullspace docs install --agent all from the project directory after installing the MCP extra. The command installs local Markdown docs and project-local agent instructions without requiring an API key. Self-hosted setup: Self-Hosted Single-Host.