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

​
Client Auth And Endpoint

VariableRequiredDescription
NULLSPACE_API_KEYYesRuntime API key used by SDK, CLI, MCP server, and raw HTTP sandbox requests. Private beta users receive this key from the Nullspace team.
NULLSPACE_API_URLYes for hosted beta; recommended for self-host clientsBase 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_URLOptionalCompatibility alias used by some scenario harnesses. Prefer NULLSPACE_API_URL.
NULLSPACE_DOCS_URLOptionalPublic 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.

​
Sandbox Create-Time Env Vars

Pass runtime values into a sandbox with Sandbox.create(envs={...}): 
from nullspace import Sandbox

with Sandbox.create(
    template="base",
    envs={"APP_ENV": "staging", "RUN_ID": "run_123"},
) as sandbox:
    print(sandbox.commands.run("echo $APP_ENV", shell=True).stdout)
Create-time env vars are visible to processes inside that sandbox. 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 sandbox.commands.run(envs={...}): 
result = sandbox.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 sandbox 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:
ScopeUse
Build-time envValues needed while building an image or template. Prefer registry auth helpers for registry credentials.
Runtime template envDefaults baked into the template for future sandboxes.
Create-time envPer-sandbox overrides passed with Sandbox.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: 
sandbox.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 sandbox create time:
TemplateEnv vars
codexCODEX_API_KEY or OPENAI_API_KEY
claude-codeANTHROPIC_API_KEY
ampAMP_API_KEY
opencodeANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENCODE_API_KEY; optional OPENCODE_*_MODEL vars
import os

with Sandbox.create(
    template="codex",
    envs={"CODEX_API_KEY": os.environ["CODEX_API_KEY"]},
) as sandbox:
    ...
Avoid writing provider keys into /workspace, shell history, logs, or template files. Rotate keys if a sandbox 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.
VariableRequiredDescription
VITE_NULLSPACE_API_BASEYes for hosted console buildsPublic 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_PATHOnly for path-mounted buildsBrowser 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_ORIGINYes for hosted console buildsCanonical console URL for browser redirects. Include /console for path-mounted appliance builds.
VITE_SUPABASE_URLOnly when self-serve Auth is re-enabledSupabase project URL used by the dormant browser session client.
VITE_SUPABASE_ANON_KEYOnly when self-serve Auth is re-enabledSupabase anon key used by the dormant browser session client.
VITE_TURNSTILE_SITE_KEYOnly when self-serve Auth is re-enabledCloudflare Turnstile site key for signup/signin/password-reset verification flows.
VITE_SUPABASE_OAUTH_ENABLEDOptional, default falseSet 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

FeatureNotes
Template buildsRegistry credentials should be passed through template auth helpers rather than persisted in files.
OSS single-host applianceOperators 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 fencingAPI 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.
Background artifact prewarmDeployment 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 checkoutDeployment 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 URLsDeployment operators configure public hostname, edge token TTL, and preview rate limits; users consume signed URLs from the SDK.
VolumesShared-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.