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 or NULLSPACE_TOKEN with NULLSPACE_API_URL directly
for scripts, CI, and coding agents.
Functions
dev, deploy, run, and shell commands are the first-class
Function workflow. The functions ... group exposes deployment, run/service,
debugging, trigger, rollback, and proxy-auth operations.
functions template ... is a nested alias for the same implementation as
template ...; use it when a Function workflow needs a custom machine
environment.
functions deploy --dry-run performs local config detection and bundle planning
without an API key. Real deploy creates or reuses a named function and stores
a metadata-only version record with the local bundle manifest; binary bundle
upload and runtime execution are handled by the function runtime path.
Functions run as finite jobs or long-running services. Jobs create run records,
logs, outputs, and backing machine access. Services create service instances
with URL, readiness, logs, and backing machine access.
Current Function modes are job and service. worker, triggered,
workspace, and interactive are reserved for future Function modes.
Lifecycle webhooks are machine lifecycle subscriptions, not agent trigger
webhooks.
Named routes let one Function version expose multiple entrypoints. Use
--route /name on run, spawn, schedule create, webhook create, and
run-branch commands to target a route-specific command.
Function environments scope names, secrets, version history, and name-based
run/spawn/rollback lookups. Use nullspace environment create/list,
NULLSPACE_ENVIRONMENT, or command-level --env / --environment selectors
to route deploys and runtime commands to default, staging, prod, or
another environment. A bare --env staging selects the Function environment;
--env NAME=value remains a runtime env-var override.
Function build cache status is reported by functions 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 function 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.
Use checkpoint, branch, tree, and rollback for snapshot-based Function
lineage. Checkpoints can be captured from job runs or service instances; branch
creates child runs or child services; rollback changes the active version for
future work.
functions proxy-auth create/list/revoke manages edge-enforced Function
endpoint credentials for versions deployed with requires_proxy_auth=True.
Create output includes the proxy-auth secret once; list output never returns
the secret.
functions schedule ... manages cron/period triggers that create normal
Function runs, and functions webhook ... manages inbound HMAC-verified
Function webhook triggers. Lifecycle webhooks are outbound machine lifecycle
subscriptions, not inbound Function triggers.
Secrets
function.py.
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 create, get,
wait, cancel, and list.
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
nullspace functions template ....
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.