> ## Documentation Index > Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt > Use this file to discover all available pages before exploring further. # Environment Variables > User-facing environment variables for the SDK, CLI, console, hosted beta, machine runtime, and agent secrets. 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](./hosted-endpoints). Self-hosted single-host users usually set `http://localhost` for localhost/no-domain mode or `https://` 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 ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} export NULLSPACE_API_KEY=ns_live_... export NULLSPACE_API_URL=https://api.your-nullspace-domain ``` ### PowerShell ```powershell theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} $env:NULLSPACE_API_KEY = "ns_live_..." $env:NULLSPACE_API_URL = "https://api.your-nullspace-domain" ``` ### Project `.env` ```dotenv theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} NULLSPACE_API_KEY=ns_live_... NULLSPACE_API_URL=https://api.your-nullspace-domain ``` The SDK and CLI lookup order is documented in [SDK config](./config). ## Machine Create-Time Env Vars Pass runtime values into a machine with `Machine.create(envs={...})`: ```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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={...})`: ```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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: ```toml theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} [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`. ```bash theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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](../templates/start-ready). ## Code Interpreter Env Vars Code interpreter runs can receive execution-specific values: ```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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 | ```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}} 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.` 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. ## Related * [API keys](../guides/api-keys) * [Account](../account) * [Agents](../agents/overview) * [Hosted endpoints](./hosted-endpoints) * [Self-hosted single-host](../quickstarts/self-hosted-single-host)