Environment Variables

Environment variables fall into different scopes. Keep client credentials in your local process or secret manager, pass machine secrets explicitly with envs=, and avoid writing provider keys into machine files.

Client Auth And Endpoint

Variable	Required	Description
`NULLSPACE_API_KEY`	Yes	Runtime API key used by SDK, CLI, MCP server, and raw HTTP machine requests. Private beta users receive this key from the Nullspace team.
`NULLSPACE_API_URL`	Yes for hosted beta; recommended for self-host clients	Base URL for the API. Hosted beta users use the value from Hosted endpoints. Self-hosted single-host users usually set `http://localhost` for localhost/no-domain mode or `https://<owned-domain>` for owned-domain mode.
`NULLSPACE_BASE_URL`	Optional	Compatibility alias used by some scenario harnesses. Prefer `NULLSPACE_API_URL`.
`NULLSPACE_DOCS_URL`	Optional	Public docs URL for scripts, handouts, and runbooks that need to print docs links.

The SDK and CLI also accept explicit api_key= and base_url= arguments when per-process overrides are safer than ambient environment variables.

Bash Or Zsh

export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain

PowerShell

$env:NULLSPACE_API_KEY = "ns_live_..."
$env:NULLSPACE_API_URL = "https://api.your-nullspace-domain"

Project `.env`

NULLSPACE_API_KEY=ns_live_...
NULLSPACE_API_URL=https://api.your-nullspace-domain

The SDK and CLI lookup order is documented in SDK config.

Machine Create-Time Env Vars

Pass runtime values into a machine with Machine.create(envs={...}):

from nullspace import Machine

with Machine.create(
    template="base",
    envs={"APP_ENV": "staging", "RUN_ID": "run_123"},
) as machine:
    print(machine.commands.run("echo $APP_ENV", shell=True).stdout)

Create-time env vars are visible to processes inside that machine. They are not stored in your local SDK config and should not be confused with NULLSPACE_API_KEY, which authenticates the client to the Nullspace API.

Per-Command Env Vars

Pass short-lived command values with machine.commands.run(envs={...}):

result = machine.commands.run(
    "python3 script.py",
    shell=True,
    envs={"PYTHONUNBUFFERED": "1"},
)

Per-command env vars are added to that process environment only. They do not change the machine default environment for later commands.

Agent Deployment Runtime Env Vars

Agent deployment config stores env var names only:

[env]
required = ["OPENAI_API_KEY"]
optional = ["SERPER_API_KEY"]

Pass values when you start runtime work. Python SDK calls accept envs=, and the CLI accepts --env NAME=value plus --env-file on agent run, service-starting agent url, agent restart, and agent dev.

nullspace agent run repo-review \
  --env OPENAI_API_KEY="$OPENAI_API_KEY"

Runtime values are injected into the agent process and are not stored in deployment config, run rows, service rows, or platform-owned event metadata. Application code can still print secrets to stdout/stderr or write them to files, so treat .env files and runtime logs as sensitive material. Agent deployment permissions are declared separately in [permissions]. Use that section for internet access, outbound allow/deny rules, service public URL policy, failed-run retention, and resource ceilings. Do not use env vars to grant host filesystem or control-plane access to agent code. There is no deployment secret store in P0. Future secret_ref objects are reserved for a brokered secret system, but current runtime env values must be literal request-time strings supplied by the SDK, CLI, or local process environment.

Template Env Vars

Template builder env vars and runtime defaults are separate:

Scope	Use
Build-time env	Values needed while building an image or template. Prefer registry auth helpers for registry credentials.
Runtime template env	Defaults baked into the template for future machines.
Create-time env	Per-machine overrides passed with `Machine.create(envs={...})`.

Start-ready commands do not receive create-time env vars unless the template defines them as runtime defaults. See Start-ready commands.

Code Interpreter Env Vars

Code interpreter runs can receive execution-specific values:

machine.code_interpreter.run_code(
    "import os; print(os.environ['RUN_ID'])",
    envs={"RUN_ID": "analysis-1"},
)

Use this for run IDs, non-secret options, and short-lived task configuration.

Agent Provider Secrets

Coding-agent templates receive only the provider keys you pass at machine create time:

Template	Env vars
`codex`	`CODEX_API_KEY` or `OPENAI_API_KEY`
`claude-code`	`ANTHROPIC_API_KEY`
`amp`	`AMP_API_KEY`
`opencode`	`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENCODE_API_KEY`; optional `OPENCODE_*_MODEL` vars

import os

with Machine.create(
    template="codex",
    envs={"CODEX_API_KEY": os.environ["CODEX_API_KEY"]},
) as machine:
    ...

Avoid writing provider keys into /workspace, shell history, logs, or template files. Rotate keys if a machine or log stream exposes them.

Console Sessions

The console is API-key based for the hosted private beta and the self-hosted single-host appliance. Users normally do not need to set local environment variables for console sessions. Deployment operators embed these values at console build time. Single-host appliance builds use infra/deploy/console.single-host-oss.env.example.

Variable	Required	Description
`VITE_NULLSPACE_API_BASE`	Yes for hosted console builds	Public API base URL used by console REST and WebSocket calls. Set to `same-origin` for `/console` appliance builds served by Caddy on the API origin. Without this value, local development defaults to `http://localhost:3000`.
`VITE_NULLSPACE_CONSOLE_BASE_PATH`	Only for path-mounted builds	Browser router and asset base path. Use `/console` for localhost/no-domain appliance mode and leave unset for root or `console.<domain>` serving.
`VITE_NULLSPACE_CONSOLE_ORIGIN`	Yes for hosted console builds	Canonical console URL for browser redirects. Include `/console` for path-mounted appliance builds.
`VITE_SUPABASE_URL`	Only when self-serve Auth is re-enabled	Supabase project URL used by the dormant browser session client.
`VITE_SUPABASE_ANON_KEY`	Only when self-serve Auth is re-enabled	Supabase anon key used by the dormant browser session client.
`VITE_TURNSTILE_SITE_KEY`	Only when self-serve Auth is re-enabled	Cloudflare Turnstile site key for signup/signin/password-reset verification flows.
`VITE_SUPABASE_OAUTH_ENABLED`	Optional, default `false`	Set to `true` only when self-serve Auth is enabled, Google/GitHub providers are enabled in Supabase, and the API has `NULLSPACE_AUTH_OAUTH_ENABLED=true`.

Auth Email Delivery

Signup verification, password reset, magic-link, and email-change messages are sent by Supabase Auth through Google SMTP relay. Configure the relay in infra/supabase/config.toml for local Supabase and in the hosted Supabase Dashboard Custom SMTP settings. These SMTP values are not read by nullspace-api. This plumbing is dormant while the private-beta console is beta-key-only.

Supabase Auth Providers

Local Supabase reads GitHub and Google OAuth client IDs and secrets from infra/supabase/config.toml via SUPABASE_AUTH_EXTERNAL_GITHUB_CLIENT_ID, SUPABASE_AUTH_EXTERNAL_GITHUB_SECRET, SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_ID, and SUPABASE_AUTH_EXTERNAL_GOOGLE_SECRET, but the local provider sections stay disabled until explicitly enabled for an OAuth smoke. Hosted deployments configure the same providers in the Supabase Dashboard. OAuth is not visible in the current beta-key-only console. Operators should only enable it after NULLSPACE_SELF_SERVE_AUTH_ENABLED=true, API/console OAuth flags, and Supabase-native CAPTCHA/hooks are configured.

Feature-Specific Vars

Feature	Notes
Template builds	Registry credentials should be passed through template auth helpers rather than persisted in files.
OSS single-host appliance	Operators should start from `infra/deploy/single-host-oss.env.example`, which sets `NULLSPACE_DISTRIBUTION=single_host_oss`, and `infra/deploy/console.single-host-oss.env.example` for the static console artifact. These keep local development `.env.example` separate from the production appliance profile. The appliance storage contract keeps `/var/lib/nullspace/data`, template-control, snapshots, runtime artifact cache, and active rootfs sources on one XFS reflink-capable filesystem. Run `nullspace-host launch-gate` on supported Ubuntu x86_64 KVM hardware before making public release claims.
Durable placement fencing	API placement uses `NULLSPACE_FEATURE_RESOURCE_LEASES=true` by default so create, snapshot restore, resume, and fork acquire database-backed capacity fences before host-agent dispatch. Production DB-backed control planes fail startup if this flag is explicitly disabled.
Dataplane pressure scheduling	Fleet operators can enable advisory pressure-aware placement with `NULLSPACE_FEATURE_DATAPLANE_PRESSURE_SCHEDULER=true` on the API. Edge pressure publishing runs every `NULLSPACE_EDGE_DATAPLANE_PRESSURE_PUBLISH_INTERVAL_SECS` seconds by default, and `0` disables edge publishing while keeping local edge metrics.
Internal route grants	Multi-host edge deployments configure `NULLSPACE_INTERNAL_ROUTE_GRANT_KEY_ID`, `NULLSPACE_INTERNAL_ROUTE_GRANT_SIGNING_KEY`, and host-agent `NULLSPACE_INTERNAL_ROUTE_GRANT_PREVIOUS_KEYS` for edge-to-host route grant signing and rotation. Enable `NULLSPACE_FEATURE_INTERNAL_ROUTE_GRANTS_STRICT=true` on host agents only after observe-mode compatibility counters are understood.
Background artifact prewarm	Deployment operators can enable the control-plane background prewarm controller with `NULLSPACE_FEATURE_RUNTIME_ARTIFACT_BACKGROUND_PREWARM=true` after Supabase durability, runtime artifact manifests, and host-agent credentials are configured. `NULLSPACE_RUNTIME_ARTIFACT_PREWARM_HOT_TEMPLATES` optionally lists templates to prewarm without lifecycle traffic.
Parked VM checkout	Deployment operators can enable sub-second base-template checkout with `NULLSPACE_FEATURE_PARKED_VM_CHECKOUT=true` and opt into automatic warming by setting `NULLSPACE_PARKED_VM_POOL_TARGET_READY` above `0`. Pool TTL, stale reap, controller concurrency, and the HA controller lease are controlled by the `NULLSPACE_PARKED_VM_POOL_*` variables.
Preview URLs	Deployment operators configure public hostname, edge token TTL, and preview rate limits; users consume signed URLs from the SDK.
Volumes	Shared-volume backends are deployment configured; SDK users create and mount logical volumes.

Operator Variables

The full deployment matrix lives in the repository at docs/product/reference/env-vars.md, with the supported OSS appliance profile in infra/deploy/single-host-oss.env.example. Public docs intentionally keep hosted SDK variables separate from operator configuration.

Python SDK

Python SDK objects

TypeScript SDK

CLI

Platform reference

Environment Variables

Client Auth And Endpoint

Bash Or Zsh

PowerShell

Project `.env`

Machine Create-Time Env Vars

Per-Command Env Vars

Agent Deployment Runtime Env Vars

Template Env Vars

Code Interpreter Env Vars

Agent Provider Secrets

Console Sessions

Auth Email Delivery

Supabase Auth Providers

Feature-Specific Vars

Operator Variables

​Client Auth And Endpoint

​Bash Or Zsh

​PowerShell

​Project .env

​Machine Create-Time Env Vars

​Per-Command Env Vars

​Agent Deployment Runtime Env Vars

​Template Env Vars

​Code Interpreter Env Vars

​Agent Provider Secrets

​Console Sessions

​Auth Email Delivery

​Supabase Auth Providers

​Feature-Specific Vars

​Operator Variables

​Related

Client Auth And Endpoint

Bash Or Zsh

PowerShell

Project `.env`

Machine Create-Time Env Vars

Per-Command Env Vars

Agent Deployment Runtime Env Vars

Template Env Vars

Code Interpreter Env Vars

Agent Provider Secrets

Console Sessions

Auth Email Delivery

Supabase Auth Providers

Feature-Specific Vars

Operator Variables

Related