CLI

Install the optional CLI extras:

python -m pip install "nullspace-sdk[cli]==1.0.0"

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 machine 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.

Machines

nullspace machine create --template base
nullspace machine create --template base --on-timeout pause --auto-resume
nullspace machine create --snapshot-id snap_123 --timeout 300
nullspace machine create --template desktop --resolution 1280x720 --dpi 144
nullspace machine list
nullspace machine list --state running --metadata team=eval
nullspace machine exec mch_123 --shell "echo hello"
nullspace ssh mch_123 -- python --version
nullspace machine ssh-access mch_123 --print-command
nullspace machine url mch_123 8080
nullspace machine preview-url create mch_123 8080 --expires 15m --wait
nullspace machine preview-url list mch_123 --port 8080 --json
nullspace machine preview-proxy-target create mch_123 8080 --transport http --transport websocket
nullspace machine metrics mch_123
nullspace machine metrics mch_123 --json
nullspace machine kill mch_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 machine timeout set mch_123 --seconds 300 --action hibernate when changing an existing machine. Use nullspace ssh when a local tool requires OpenSSH; it mints a short-lived certificate for the Nullspace SSH relay. Use machine 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 machine upload mch_123 ./report.txt /workspace/report.txt
nullspace machine file list mch_123 /workspace
nullspace machine file upload-url mch_123 /workspace/report.txt
nullspace machine desktop screenshot mch_123 --output screen.png
nullspace machine code run mch_123 "print('hello')" --json
nullspace snapshot create mch_123
nullspace lifecycle events --limit 20
nullspace lifecycle stream --machine-id mch_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: createMachine, destroyMachine, createVolume. Use nullspace schema to inspect the installed command tree and generated MCP tool input schemas. Install nullspace-sdk[cli,mcp]==1.0.0 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.

Python SDK

Python SDK objects

TypeScript SDK

Platform reference

CLI

Authenticate

Machines

Files and lifecycle

Volumes

​Authenticate

​Machines

​Files and lifecycle

​Volumes

Authenticate

Machines

Files and lifecycle

Volumes