Auth
.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.
Agent deployments
agent deploy --dry-run performs local config detection and bundle planning
without an API key. Real deploy creates or reuses a named deployment and stores
a metadata-only version record with the local bundle manifest; binary bundle
upload and runtime execution are handled by the deployment runtime path.
Current Agent Deployment modes are job and service. worker, triggered,
workspace, and interactive are reserved config words for future deployment
models; dry-run can show them for local planning, but live deploy/runtime
commands reject them until the API, SDK, CLI, and runtime support those modes.
Agent deployment build cache status is reported by agent deploy in human
output and in the JSON cache object. The default auto policy reports cache
eligibility and falls back to per-run install when no ready artifact is
available. Use --rebuild to build a fresh reusable deployment artifact during
upload, or --no-cache to bypass cache lookup and artifact writes for that
deploy. Use a custom template for heavy system dependencies or slow base setup.
Failed job runs can opt into retained debugging with
--retain-on-failure; retained runs expose a normal machine_id, so existing
nullspace machine ... commands work for files, exec, PTY, URLs, snapshots, and
manual destroy.
Lifecycle webhooks are machine lifecycle subscriptions, not agent trigger
webhooks.
Machines
--idempotency-key, --cwd,
--env, --env-json, --metadata, --metadata-json, --network-json,
--snapshot-id, --internet-access/--no-internet-access, --on-timeout,
--auto-resume/--no-auto-resume, --warm-pool, --warm-pool-mode,
--warm-pool-wait, desktop flags, and
repeatable --volume ref=<name-or-id>,mount=<path>[,subpath=<subpath>][,ro=true].
Prefer --on-timeout pause for create-time pause/hibernate behavior. The
lower-level --timeout-action flag exists for raw API parity, but most CLI
workflows should use --on-timeout at create time and
machine timeout set --action ... for existing machines.
Use nullspace ssh when a local tool requires OpenSSH; it mints a
short-lived certificate for the Nullspace SSH relay.
Preview URLs
preview-url commands cover direct browser links, signed grants, inventory,
and revocation. Human output redacts token-bearing URLs by default; use --raw
only for an explicit secret-bearing display action. --json emits raw
automation-ready values plus stable metadata such as selected transport,
expiry, auth mode, readiness when --wait is used, and token-redacted usage
counters when listing grants.
Use preview-proxy-target create for customer-run reverse proxies. It returns
marker-only upstream URLs plus HTTP/WebSocket header tokens that the proxy must
forward as x-nullspace-preview-proxy-token; human output redacts those header
tokens unless --raw is supplied.
See Token model for how preview URL tokens,
preview proxy tokens, private traffic tokens, and API keys differ.
Files and processes
Desktop, code, PTY, and git
machine code run-job list is available for read-only hosted beta inspection.
machine code run-job create, get, cancel, and wait are not part of the
hosted private beta launch surface because remote host-agent routing for queued
code runs is not implemented yet.
Snapshots
Lifecycle
Monitor, schema, and MCP
nullspace mcp serve requires the MCP extra:
nullspace docs install --agent all installs project-local Markdown docs and
agent config for Claude Code and Codex. It does not require an API key and does
not edit user-level configuration files.
Templates
template build mirrors the Python builder surface for base images,
Dockerfiles, registry auth, files, package installs, build/runtime envs, start
commands, readiness probes, build CPU/memory/internet access, optional
--backend buildkit for Dockerfile builds, BuildKit request-time secrets, tags,
aliases, and visibility. Dry-run and render JSON redact registry credentials and
BuildKit secret values.
template warm-pool commands manage tenant-owned ready capacity for a template.
Machine create --warm-pool-mode prefer cold-falls back on a miss, require
returns warm_pool_unavailable, and bypass forces cold create.
Dockerfile builds use BuildKit. --backend native is rejected for Dockerfile
builds.