Nora environment variable reference

Complete reference for every environment variable Nora reads, grouped by category, with required flags, defaults, and configuration guidance.

Every Nora deployment is configured through environment variables. Start by copying .env.example to .env in your project root, then replace all <REPLACE_...> placeholders with real values before starting the stack. The sections below describe every variable Nora reads, grouped by function.

Settings — the provider-keys surface that several environment variables ultimately drive

Generate cryptographic secrets with the following command. Never reuse secrets across deployments or commit them to version control.

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Required

These variables must be set before the stack will start. Without them, JWTs cannot be signed, stored credentials cannot be encrypted, backup archives cannot be sealed, and Agent Hub source-catalog API keys cannot be hashed.

Variable	Required	Default	Description
`JWT_SECRET`	Yes	—	Secret used to sign all JWTs. Minimum 32 characters. In production the backend refuses to boot when this is missing, too short, or looks like a placeholder (e.g. an unedited `.env.example` value). In development a generated secret is persisted in the database so sessions survive restarts.
`ENCRYPTION_KEY`	Yes	—	32-byte hex key (64 hex characters) for AES-256-GCM encryption of stored provider keys, integration credentials, and other sensitive values. In production the backend refuses to boot when this is missing or invalid unless `NORA_ALLOW_PLAINTEXT_SECRETS=true` is set explicitly.
`NORA_BACKUP_ENCRYPTION_KEY`	Yes	—	32-byte hex key for sealing managed backup archives. Required to create or restore backups. Do not rotate casually — archives encrypted with the previous key cannot be decrypted with a new one.
`NORA_AGENT_HUB_API_KEY_HASH_SECRET`	Yes	—	HMAC secret for hashing Agent Hub source-catalog API keys at rest. `setup.sh` auto-generates this on first run; rotating it invalidates every issued Agent Hub key.
`NORA_API_KEY_HASH_SECRET`	Yes	—	Primary HMAC secret for workspace/API token hashes. Setup preserves an existing value; when upgrading an older install it copies the legacy Agent Hub/encryption/JWT fallback so existing tokens remain valid.
`NORA_ALLOW_PLAINTEXT_SECRETS`	No	`false`	Explicit override to boot a production instance without a valid `ENCRYPTION_KEY` (credentials are then stored unencrypted). Only for throwaway/demo environments.

Secret files

Production Compose and Helm deployments mount core credentials read-only under /run/secrets instead of exposing them to frontend containers. The production control-plane entrypoint loads files whose names are valid environment-variable names. A non-empty direct environment value takes precedence; custom orchestrators can use these conventional aliases:

Variable	Default	Target environment variable
`JWT_SECRET_FILE`	—	`JWT_SECRET`
`ENCRYPTION_KEY_FILE`	—	`ENCRYPTION_KEY`
`NORA_BACKUP_ENCRYPTION_KEY_FILE`	—	`NORA_BACKUP_ENCRYPTION_KEY`
`NORA_AGENT_HUB_API_KEY_HASH_SECRET_FILE`	—	`NORA_AGENT_HUB_API_KEY_HASH_SECRET`
`NORA_API_KEY_HASH_SECRET_FILE`	—	`NORA_API_KEY_HASH_SECRET`
`DB_PASSWORD_FILE`	—	`DB_PASSWORD`

The setup scripts keep .env owner-only: mode 0600 on macOS/Linux/WSL and a protected, non-inherited ACL on Windows. Treat timestamped .env.backup-* files with the same sensitivity. For Compose, setup also materializes the six core values as individual files under NORA_COMPOSE_SECRETS_DIR (default .secrets/compose). The directory is gitignored and restricted to the owner; Compose mounts only the requested files read-only into control-plane containers. Operators who bypass setup must run bash scripts/materialize-compose-secrets.sh <env-file> before Compose startup and after rotating any core value.

Variable	Default	Description
`NORA_COMPOSE_SECRETS_DIR`	`.secrets/compose`	Host directory for installer-materialized Compose secret files. Must be a dedicated, non-symlinked directory.
`COMPOSE_PROJECT_NAME`	`nora`	Stable Compose namespace used to scope setup, upgrade, and clean-reinstall container/volume operations.

Bootstrap admin account

These variables seed the first administrator account on the very first boot. They are ignored on subsequent starts once an account exists. Both must be set together. An empty hosted PaaS database requires secure explicit values and refuses to start without them; a self-hosted installation may leave both blank and claim the first administrator through /signup. Setting only one is always invalid.

Variable	Required	Default	Description
`DEFAULT_ADMIN_EMAIL`	PaaS: Yes	—	Valid, non-placeholder email address for the bootstrap admin account. Required when hosted PaaS starts with an empty user database.
`DEFAULT_ADMIN_PASSWORD`	PaaS: Yes	—	Password for the bootstrap admin account. Minimum 12 characters; placeholders and default-derived values are rejected before the API listener starts.

Do not set a weak or well-known password here. This account has full operator access from the moment the database is seeded.

Database

PostgreSQL connection settings. Defaults match the Docker Compose service name and port.

Variable	Required	Default	Description
`DATABASE_URL`	No	—	Full PostgreSQL connection URL. Takes precedence over individual fields. URL `ssl=true`/`1` is normalized to verified TLS and `ssl=false`/`0` to disabled; explicit `DB_SSL_MODE`/`DB_SSL` overrides URL TLS controls.
`DB_HOST`	No	`postgres`	PostgreSQL hostname. Compose users keep the default; external DBs override.
`DB_PORT`	No	`5432`	PostgreSQL port.
`DB_USER`	No	`nora`	Database role used by backend-api and workers.
`DB_PASSWORD`	Yes	—	Password for the role above. For compose installs, keep this value aligned with the initialized Postgres volume; setup preserves it during reconfigure mode.
`DB_PASSWORD_FILE`	No	—	Path to a file containing `DB_PASSWORD`. Production Compose sets this to `/run/secrets/DB_PASSWORD`; the direct value wins when both are non-empty.
`DB_NAME`	No	`nora`	Database name.
`DB_SSL_MODE`	No	URL policy or off	TLS policy: `disable`, `require`, `verify-ca`, or `verify-full`. Blank honors `DATABASE_URL` SSL parameters; an explicit value overrides conflicting URL TLS parameters. Verification modes require a CA.
`DB_SSL_CA`	No	—	Inline PEM CA certificate; escaped `\\n` sequences are expanded.
`DB_SSL_CA_FILE`	No	—	Path to a mounted CA certificate.
`DB_SSL_CERT`	No	—	Inline client certificate for mutual TLS.
`DB_SSL_CERT_FILE`	No	—	Path to a mounted client certificate.
`DB_SSL_KEY`	No	—	Inline client private key for mutual TLS.
`DB_SSL_KEY_FILE`	No	—	Path to a mounted client private key.
`DB_POOL_MAX`	No	`20`	Maximum PostgreSQL pool size per process.
`DB_IDLE_TIMEOUT_MS`	No	`30000`	Idle pooled-connection timeout.
`DB_CONNECTION_TIMEOUT_MS`	No	`10000`	Connection acquisition timeout.
`DB_STATEMENT_TIMEOUT_MS`	No	`0`	PostgreSQL statement timeout for normal application queries; `0` leaves it disabled.
`DB_MIGRATION_LOCK_TIMEOUT_MS`	No	`60000`	Maximum startup wait for Nora’s migration advisory lock before failing closed. Clamped to 1 second–10 minutes.
`DB_MIGRATION_STATEMENT_TIMEOUT_MS`	No	`600000`	Transaction-local timeout for migration ledger, legacy-repair, and migration statements. Clamped to 1 second–60 minutes.

Redis and queue

Redis backs BullMQ for deployment, ClawHub install, backup, and alert-delivery jobs.

Variable	Required	Default	Description
`REDIS_URL`	No	—	Full Redis URL. Takes precedence over `REDIS_HOST` and `REDIS_PORT`.
`REDIS_HOST`	No	`redis`	Redis hostname.
`REDIS_PORT`	No	`6379`	Redis port.
`REDIS_USERNAME`	No	—	Optional ACL username.
`REDIS_PASSWORD`	No	—	Optional Redis password. Set when Redis is exposed outside the compose network.
`REDIS_DB`	No	`0`	Redis logical database index.
`REDIS_TLS`	No	`false`	Enables TLS for the Redis connection.
`REDIS_TLS_CA`	No	—	Inline PEM CA certificate.
`REDIS_TLS_CA_FILE`	No	—	Path to a mounted Redis CA certificate.
`REDIS_TLS_CERT`	No	—	Inline client certificate for mutual TLS.
`REDIS_TLS_CERT_FILE`	No	—	Path to a mounted Redis client certificate.
`REDIS_TLS_KEY`	No	—	Inline client private key for mutual TLS.
`REDIS_TLS_KEY_FILE`	No	—	Path to a mounted Redis client private key.
`REDIS_TLS_INSECURE_SKIP_VERIFY`	No	`false`	Disables Redis certificate verification. Test-only; never use on an untrusted network.
`REDIS_CONNECT_TIMEOUT_MS`	No	`10000`	Redis connection timeout.
`PORT`	No	`4000`	Backend-api listen port inside the container.
`BACKEND_API_PORT`	No	`4100`	Host-only backend API port mapped to container `PORT`. Setup auto-picks another free port when `127.0.0.1:4100` is busy.
`DEPLOYMENT_WORKER_CONCURRENCY`	No	`6`	How many deployment jobs the provisioner worker runs in parallel. Higher values reduce queued time but increase image-pull and bootstrap pressure.
`DEPLOYMENT_JOB_TIMEOUT_MS`	No	`900000`	Timeout per deployment job, in milliseconds. Aliased by `PROVISION_TIMEOUT_MS` for legacy deployments.
`CLAWHUB_INSTALL_TIMEOUT_MS`	No	`300000`	Timeout per ClawHub skill install job, in milliseconds.
`HERMES_SKILLS_INSTALL_TIMEOUT_MS`	No	`300000`	Timeout per Hermes skill install/uninstall job, in milliseconds.
`HERMES_SKILLS_REGISTRY_URL`	No	—	Overrides the aggregated Hermes skills index URL (`https://hermes-agent.nousresearch.com/docs/api/skills-index.json`) used by the skills browse/search/detail API.
`HERMES_SKILLS_INDEX_TTL_MS`	No	`3600000`	How long the fetched Hermes skills index is cached (in memory and on disk) before a refresh. When a refresh fails, the cached copy is served marked stale instead of failing browse requests.
`BACKUP_WORKER_CONCURRENCY`	No	`2`	Backup worker concurrency.
`NORA_BACKUP_JOB_TIMEOUT_MS`	No	`1800000`	Backup job hard timeout. The backup worker enforces this via `Promise.race` because BullMQ v5 ignores `defaultJobOptions.timeout`.
`NORA_BACKUP_SCHEDULE_POLL_MS`	No	`60000`	How often the backup worker checks for due scheduled backups.
`AGENT_PROVISION_LOCK_TIMEOUT_MS`	No	`30000`	Maximum wait for the shared per-agent provision lock used by replacement producers and destructive restore. On timeout Nora rejects the transition instead of racing an active worker.
`ALERT_DELIVERY_ATTEMPTS`	No	`5`	Number of retry attempts for an alert webhook delivery before the worker records a terminal failure on the rule. Clamped to `[1, 10]`.
`ALERT_DELIVERY_WORKER_CONCURRENCY`	No	`5`	Concurrency of the alert-deliveries worker.
`WORKER_HEALTH_PORT`	No	`4001`	Provisioner worker health-check port.
`BACKUP_WORKER_HEALTH_PORT`	No	`4002`	Backup worker health-check port.
`CLAWHUB_PRUNE_ORPHANED_SKILLS`	No	`false`	When `true`, the provisioner reconciler uninstalls ClawHub skills present in a runtime container but not tracked in the agents table. Off by default — orphans are surfaced in the UI and removed explicitly.
`HERMES_PRUNE_ORPHANED_SKILLS`	No	`false`	When `true`, the provisioner reconciler uninstalls hub-installed Hermes skills present in a runtime but not tracked in the agents table. Off by default — orphans are surfaced in the UI and removed explicitly.

Access and URL

These variables control which nginx configuration is mounted, the listening port, and the public-facing base URL.

Variable	Required	Default	Description
`NGINX_CONFIG_FILE`	No	`nginx.conf`	Nginx configuration to mount. Use `nginx.conf` for local-only mode and `nginx.public.conf` for public-domain mode.
`NGINX_HTTP_PORT`	No	`8080`	Host port mapped to the nginx HTTP listener. Use `8080` locally and `80` when deploying on a public domain. Setup auto-picks another free local port when `8080` is busy.
`NEXTAUTH_URL`	No	`http://localhost:8080`	Canonical browser-facing URL of your Nora deployment. Set to your `https://` origin when exposing on a domain.
`NORA_PUBLIC_URL`	No	—	Optional explicit public origin used by emails, OAuth callbacks, and audit links when it differs from `NEXTAUTH_URL`.
`NORA_FORCE_SECURE_COOKIES`	No	—	When set to `1`, forces the `Secure` flag on session cookies regardless of inbound scheme. Set for always-on-TLS public deployments behind a proxy/CDN that may strip `X-Forwarded-Proto`; leave empty for local HTTP.

API request rate limits

App-wide per-IP abuse protection sits in front of every route: a generous global budget for all traffic plus a tighter budget for state-changing methods (POST/PUT/PATCH/DELETE). Overrides must be positive integers; invalid values fall back to the secure defaults below. Raise them only where many requests legitimately share one source IP — for example the Playwright E2E suite, which drives the whole API from a single localhost address and otherwise self-throttles.

Variable	Required	Default	Description
`GLOBAL_RATE_LIMIT_MAX`	No	`1000`	All requests allowed per IP within the global window.
`GLOBAL_RATE_LIMIT_WINDOW_MS`	No	`900000`	Global rate-limit window in milliseconds (15 minutes).
`MUTATION_RATE_LIMIT_MAX`	No	`60`	State-changing requests (POST/PUT/PATCH/DELETE) allowed per IP/window.
`MUTATION_RATE_LIMIT_WINDOW_MS`	No	`60000`	Mutation rate-limit window in milliseconds (1 minute).

Password and OAuth login share one per-IP rate-limit budget. Overrides must be positive integers; invalid values fall back to the secure defaults below.

Variable	Required	Default	Description
`AUTH_RATE_LIMIT_MAX`	No	`20`	Combined password and OAuth login attempts allowed per IP/window.
`AUTH_RATE_LIMIT_WINDOW_MS`	No	`900000`	Login rate-limit window in milliseconds (15 minutes).

OAuth

OAuth login is disabled by default. Set OAUTH_LOGIN_ENABLED=true along with provider credentials to enable it. Provider verification must be completed in the relevant developer consoles before these values take effect.

Variable	Required	Default	Description
`OAUTH_LOGIN_ENABLED`	No	`false`	Set to `true` to activate OAuth login.
`GOOGLE_CLIENT_ID`	No	—	OAuth 2.0 client ID from Google Cloud Console.
`GOOGLE_CLIENT_SECRET`	No	—	OAuth 2.0 client secret from Google Cloud Console.
`GITHUB_CLIENT_ID`	No	—	OAuth App client ID from GitHub Developer Settings.
`GITHUB_CLIENT_SECRET`	No	—	OAuth App client secret from GitHub Developer Settings.
`NEXTAUTH_SECRET`	No	—	Secret used by NextAuth.js for session encryption. Required when OAuth is enabled.

Signup remains public, but Nora bounds signup spikes with dedicated app-level rate limits and a runtime bot challenge. Self-hosted operators may explicitly opt out; hosted PaaS signup fails closed until Turnstile or reCAPTCHA is fully configured.

Variable	Required	Default	Description
`SIGNUP_RATE_LIMIT_BURST_MAX`	No	`5`	Maximum signup attempts per IP within the burst window.
`SIGNUP_RATE_LIMIT_BURST_WINDOW_MS`	No	`600000`	Burst signup window in milliseconds.
`SIGNUP_RATE_LIMIT_DAILY_MAX`	No	`20`	Maximum signup attempts per IP within the daily window.
`SIGNUP_RATE_LIMIT_DAILY_WINDOW_MS`	No	`86400000`	Sustained signup window in milliseconds.
`SIGNUP_BOT_PROTECTION_PROVIDER`	PaaS: Yes	`none`	Runtime challenge provider: `none`, `turnstile`, or `recaptcha`. Hosted PaaS signup fails closed when this is `none`; self-hosted operators may opt out.
`SIGNUP_TURNSTILE_SITE_KEY`	No	—	Cloudflare Turnstile public site key. Required with the Turnstile provider and exposed through bootstrap status.
`SIGNUP_TURNSTILE_SECRET`	No	—	Cloudflare Turnstile verification secret. Required with the Turnstile provider and retained only by the backend.
`SIGNUP_RECAPTCHA_SITE_KEY`	No	—	Google reCAPTCHA public site key. Required with the reCAPTCHA provider and exposed through bootstrap status.
`SIGNUP_RECAPTCHA_SECRET`	No	—	Google reCAPTCHA verification secret. Required with the reCAPTCHA provider and retained only by the backend.

The signup page reads this configuration at runtime from GET /api/auth/bootstrap-status, so published frontend images do not need provider-specific build arguments. Existing NEXT_PUBLIC_SIGNUP_BOT_PROTECTION_PROVIDER, NEXT_PUBLIC_SIGNUP_TURNSTILE_SITE_KEY, and NEXT_PUBLIC_SIGNUP_RECAPTCHA_SITE_KEY values remain accepted as deprecated runtime aliases; setup migrates their values into the canonical names above.

The reference production workflow refuses a PLATFORM_MODE=paas deployment unless the selected provider has both its public site key and server secret. This preflight runs before release metadata, secret materialization, image builds, or Compose replacement so a release cannot deploy public signup into a known unavailable state.

Release tracking and upgrades

Drives the admin “release available” banner and the one-click upgrade runner. Setting NORA_GITHUB_REPO enables Nora to compare the running version against the latest published GitHub release.

Variable	Required	Default	Description
`NORA_CURRENT_VERSION`	No	—	Current running version, set by your deploy pipeline.
`NORA_CURRENT_COMMIT`	No	—	Commit SHA of the running build.
`NORA_GITHUB_REPO`	No	`solomon2773/nora`	`owner/repo` used to query the GitHub Releases API.
`NORA_GITHUB_TOKEN`	No	—	Optional PAT to raise the GitHub API rate limit.
`NORA_RELEASE_CACHE_TTL_MS`	No	`300000`	How long to cache the latest-release lookup, in milliseconds.
`NORA_LATEST_VERSION`	No	—	Manual override for the latest version. Skips the GitHub query when set.
`NORA_LATEST_PUBLISHED_AT`	No	—	Manual override for the latest release timestamp.
`NORA_RELEASE_NOTES_URL`	No	—	URL displayed alongside the upgrade banner.
`NORA_LATEST_SEVERITY`	No	`warning`	Severity of the upgrade banner. One of `info`, `warning`, `critical`.
`NORA_UPGRADE_REQUIRED`	No	`false`	Set to `true` to display a hard-required upgrade banner.
`NORA_AUTO_UPGRADE_ENABLED`	No	`false`	Opt-in to one-click upgrades from Admin Settings.
`NORA_HOST_REPO_DIR`	No	—	Absolute Linux host path to this Nora checkout. Auto-filled by `setup.sh`.
`NORA_UPGRADE_REPO`	No	`https://github.com/solomon2773/nora.git`	Git URL used by the upgrade runner.
`NORA_UPGRADE_REF`	No	`master`	Branch or ref the upgrade runner pulls.
`NORA_UPGRADE_RUNNER_IMAGE`	No	`docker:29-cli`	Container image the upgrade runner executes inside.
`NORA_UPGRADE_STATE_VOLUME`	No	`nora_upgrade_state`	Docker volume that persists upgrade state between runs.
`NORA_ENV_FILE`	No	`.env`	Deploy env file passed to Docker Compose during one-click upgrades.
`NORA_UPGRADE_COMPOSE_FILES`	No	auto-detected	Colon-separated compose file list used by the upgrade runner. Leave blank to reuse Docker Compose labels from the running backend container.
`NORA_UPGRADE_PUBLIC_HEALTH_URL`	No	—	Optional public health URL checked after the stack rebuilds, for example `https://stage.example.com/api/health`.
`NORA_UPGRADE_HEALTHCHECK_ATTEMPTS`	No	`221`	Attempts for setup and upgrade probes. At the 3-second default, attempt 221 runs after 660 seconds; maximum window is 3900 seconds.
`NORA_UPGRADE_HEALTHCHECK_INTERVAL_SECONDS`	No	`3`	Seconds between those probes. Positive integers only; the combined first-to-final window must be at most 3900 seconds.
`NORA_INSTALL_METHOD`	No	`source`	Install method shown in admin UI. One of `source`, `docker_image`, `custom`.
`NORA_MANUAL_UPGRADE_COMMAND`	No	`./setup.sh --update`	Command displayed when auto-upgrade is disabled.
`NORA_MANUAL_UPGRADE_STEPS`	No	—	Optional override for the displayed manual-upgrade steps.

The former built-in 40 attempts / 3 seconds pair is treated as a legacy default and upgraded to 221 / 3; other valid custom pairs are preserved.

Variable	Required	Default	Description
`NORA_SYSTEM_BANNER_ENABLED`	No	`false`	Master switch for the admin-configured banner shown across `/app` and `/admin`. Banner copy and severity are managed in Admin Settings.

Platform mode

Variable	Required	Default	Description
`PLATFORM_MODE`	No	`selfhosted`	Operating mode. `selfhosted` uses operator-defined request limits with no billing. `paas` enables Stripe billing; plan tiers control agent-count and managed-backup entitlements while per-agent compute uses operator-managed platform defaults. See Platform modes for full details.

Self-hosted resource limits

These variables are only read when PLATFORM_MODE=selfhosted. They define the maximum resources any single user can request when deploying an agent.

Variable	Required	Default	Description
`MAX_VCPU`	No	`16`	Maximum vCPUs a user may allocate to a single agent.
`MAX_RAM_MB`	No	`32768`	Maximum RAM in megabytes a user may allocate to a single agent.
`MAX_DISK_GB`	No	`500`	Maximum requested `disk_gb`; actual storage enforcement depends on the deploy target.
`MAX_AGENTS`	No	`50`	Maximum number of agents a single user may deploy.

Billing / Stripe

These variables are only read when PLATFORM_MODE=paas. See Platform modes for a full explanation of PaaS mode.

Variable	Required	Default	Description
`BILLING_ENABLED`	No	`false`	Set to `true` to enforce Stripe subscription limits. When `false` in PaaS mode, deployments are unlimited.
`STRIPE_SECRET_KEY`	No	—	Stripe secret key. Use `sk_test_...` for testing and `sk_live_...` for production.
`STRIPE_WEBHOOK_SECRET`	No	—	Stripe webhook signing secret (`whsec_...`) for verifying incoming webhook events.
`STRIPE_PRICE_PRO`	No	—	Stripe Price ID (`price_...`) for the Pro subscription tier.
`STRIPE_PRICE_ENTERPRISE`	No	—	Stripe Price ID (`price_...`) for the Enterprise subscription tier.

Runtime selection

Runtime selection is three-dimensional: runtime family × deploy target × sandbox profile. Each enabled-list variable accepts a comma-separated list. The first id in each list is the default for new deployments. See Provisioner backends for details.

Variable	Required	Default	Description
`ENABLED_RUNTIME_FAMILIES`	No	`openclaw`	Runtime families enabled. Supported ids: `openclaw`, `hermes`.
`ENABLED_BACKENDS`	No	`docker`	Env-configured deploy targets enabled. `proxmox` is opt-in and experimental. Kubernetes clusters are registered in Admin.
`ENABLED_SANDBOX_PROFILES`	No	`standard`	Sandbox profiles enabled. Supported ids: `standard`, `nemoclaw`.
`DOCKER_AGENT_BIND_IP`	No	`127.0.0.1`	Host address used for Docker-published agent gateway/runtime ports. Keep loopback unless trusted remote clients must connect; protect any wider bind with a firewall or authenticated reverse proxy.

Kubernetes registry and Compose mount helpers

Nora no longer creates Kubernetes execution targets from .env labels. Register every Kubernetes cluster in Admin -> Kubernetes. Each enabled row becomes a concrete execution target such as k8s:aks-eastus2 and stores its provider, actual cluster name, kubeconfig, namespaces, exposure mode, Service annotations, load-balancer source ranges, and load-balancer class. docker-compose.kubernetes.yml only mounts a kubeconfig directory into the Nora containers. Put one or more kubeconfig files under NORA_KUBECONFIGS_DIR, then enter /kubeconfigs/<file> as each Admin Kubeconfig path. The Admin path must be the path visible inside backend-api and worker-provisioner, not the host path. For more than one cluster, put multiple kubeconfig files under NORA_KUBECONFIGS_DIR. The Kubernetes overlay mounts that directory at /kubeconfigs, so two AKS clusters can use Admin paths such as /kubeconfigs/aks-eastus2 and /kubeconfigs/aks-westus2 while both still run through docker-compose.kubernetes.yml.

Variable	Required	Default	Description
`NORA_KUBECONFIGS_DIR`	No	`./.secrets/kubeconfigs`	Host directory mounted at `/kubeconfigs` by the Kubernetes overlay for single- or multi-cluster setups.
`CONTAINER_KUBECONFIG_PATH`	No	`/tmp/nora-kind.container.kubeconfig`	Kind smoke helper file; its parent directory is mounted as `NORA_KUBECONFIGS_DIR`.

Admin-registered encrypted kubeconfigs require ENCRYPTION_KEY because Nora stores pasted kubeconfig content encrypted at rest.

Docker agent published ports

Docker and remote-Docker agents reserve their published gateway ports in PostgreSQL. The configurable subrange must remain inside 19000-19999, which is already allowed by the gateway proxy’s default SSRF guard. Local Docker deployments skip ports published by running containers and retry a bounded number of bind conflicts, including conflicts caused by non-Docker listeners.

Variable	Required	Default	Description
`DOCKER_AGENT_PORT_RANGE_MIN`	No	`19000`	Lowest published gateway port. Must be between `19000` and `19999`.
`DOCKER_AGENT_PORT_RANGE_MAX`	No	`19999`	Highest published gateway port. Must be between `19000` and `19999` and not below the minimum.

Gateway proxy SSRF guard

Defaults allow OpenClaw’s internal gateway port, Docker-published 19000-19999, and Kubernetes NodePort 30000-32767. Override only if you publish gateways on non-default ports or hosts.

Variable	Required	Default	Description
`NORA_GATEWAY_PROXY_ALLOWED_PORTS`	No	—	Comma-separated list of additional ports the gateway proxy may target.
`NORA_GATEWAY_PROXY_ALLOWED_HOSTS`	No	—	Comma-separated list of additional hostnames the gateway proxy may target.

Remote Docker safety and authorization

Active Remote Docker gateway, log, and terminal streams periodically re-check that the agent owner still owns the host or has an editor, admin, or owner workspace grant. Lower values reduce the window before those streams close after revocation, at the cost of more authorization queries. Remote-host create, edit, Test, SSH-pin reset, delete, share, and unshare operations are serialized per host id so concurrent ownership, grant, trust, or credential mutations cannot race across backend replicas.

Variable	Required	Default	Description
`REMOTE_HOST_AUTH_RECHECK_MS`	No	`1000`	Grant recheck interval in milliseconds for active gateway, log, and terminal streams. Minimum 250.
`REMOTE_HOST_MUTATION_LOCK_TIMEOUT_MS`	No	`15000`	Maximum wait for another create/edit/Test/pin-reset/delete/share/unshare operation on the same host id. Timeout rejects the competing request (409).

Proxmox

Proxmox is an opt-in experimental LXC target for standard OpenClaw and prepared Hermes images. Keep Docker enabled while validating it, use verified API TLS and pinned SSH host keys, and run the real-host smoke before production use. NemoClaw on Proxmox remains blocked.

Variable	Required	Default	Description
`PROXMOX_API_URL`	With target	—	HTTPS Proxmox API origin or URL ending in `/api2/json`.
`PROXMOX_TOKEN_ID`	With target	—	API token ID in `user@realm!tokenname` format.
`PROXMOX_TOKEN_SECRET`	With target	—	Secret associated with the API token.
`PROXMOX_VERIFY_TLS`	No	`true`	Verifies the Proxmox API certificate. `false` is test-only.
`PROXMOX_CA_CERT` / `PROXMOX_CA_CERT_PATH`	No	—	Inline or mounted private CA certificate.
`PROXMOX_ALLOW_INSECURE_HTTP`	No	`false`	Test-only opt-in for an isolated HTTP fixture.
`PROXMOX_NODE`	No	`pve`	Proxmox node where LXCs are created.
`PROXMOX_TEMPLATE`	No	`local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst`	LXC template used for OpenClaw agents.
`PROXMOX_HERMES_TEMPLATE`	For Hermes	—	Prepared LXC template containing the Hermes executable and `hermes` user.
`PROXMOX_ROOTFS_STORAGE`	No	`local-lvm`	Storage pool used for the rootfs.
`PROXMOX_BRIDGE`	No	`vmbr0`	DHCP-capable network bridge attached to created LXCs.
`PROXMOX_SSH_HOST` / `PROXMOX_SSH_USER`	With target	— / `root`	SSH endpoint used to run `pct`.
`PROXMOX_SSH_PORT`	No	`22`	SSH port.
`PROXMOX_SSH_PRIVATE_KEY` / `_PATH`	One SSH auth method	—	Inline or mounted SSH private key.
`PROXMOX_SSH_PRIVATE_KEY_PASSPHRASE`	No	—	Passphrase for the configured private key.
`PROXMOX_SSH_PASSWORD`	One SSH auth method	—	Password fallback when key auth is not configured.
`PROXMOX_SSH_HOST_FINGERPRINT`	With target	—	Trusted OpenSSH SHA-256 host-key fingerprint.
`PROXMOX_SSH_INSECURE_ACCEPT_HOST_KEY`	No	`false`	Test-only bypass for pinned host verification.
`PROXMOX_PCT_COMMAND` / `PROXMOX_SUDO`	No	`pct` / auto	`PROXMOX_PCT_COMMAND` accepts one command name or absolute executable path with no arguments. `PROXMOX_SUDO` accepts only `sudo -n` or an absolute `sudo` path followed by `-n`; other values fail preflight.
`PROXMOX_OFFLINE_STAGE_COMMAND`	Non-root SSH only	—	One absolute path to the operator-installed strict stopped-LXC staging helper. Missing or unsafe values keep a non-root target unavailable; arguments, traversal, and shell syntax are rejected. See the helper contract.
`PROXMOX_NODE_MAJOR`	No	`24`	Minimum Node.js major installed in stock OpenClaw templates.
`PROXMOX_OPENCLAW_PACKAGE`	No	`openclaw@2026.6.11`	Package spec installed for OpenClaw. Override only after validating Gateway and activation compatibility.
`PROXMOX_HERMES_BIN`	No	`/opt/hermes/.venv/bin/hermes`	Hermes executable in the prepared template.
`PROXMOX_HERMES_ENABLE_INSECURE_DASHBOARD`	No	`false`	Binds the Hermes dashboard to `0.0.0.0` instead of `127.0.0.1`. The dashboard now always requires authentication (Hermes basic-auth provider; Nora injects a per-agent credential), so this controls only the bind address — not authentication. Leave false unless the port is separately protected.

NemoClaw / NVIDIA

Read when ENABLED_SANDBOX_PROFILES includes nemoclaw.

Variable	Required	Default	Description
`NVIDIA_API_KEY`	No	—	API key from build.nvidia.com for accessing NVIDIA-hosted Nemotron models.
`NEMOCLAW_DEFAULT_MODEL`	No	`nvidia/nemotron-3-super-120b-a12b`	Default Nemotron model used by NemoClaw agents.
`NEMOCLAW_SANDBOX_IMAGE`	No	`ghcr.io/solomon2773/nora-nemoclaw-agent:latest`	Container image for NemoClaw. Mutable registry tags refresh before Docker/Remote Docker create; normal local setup/deploy rebuilds Nora’s exact local tag, while custom refs and remote/Kubernetes preloads remain operator-owned.

OpenClaw runtime

These variables tune the OpenClaw runtime image and gateway. Most operators leave them at their defaults; override when running a forked OpenClaw build or pinning to a specific image.

Variable	Required	Default	Description
`OPENCLAW_DOCKER_IMAGE`	No	OpenClaw default	Container image used for OpenClaw agents.
`OPENCLAW_STANDARD_IMAGE`	No	OpenClaw default	Image used specifically for the `standard` sandbox profile.
`OPENCLAW_GATEWAY_PORT`	No	`18789`	Internal port the OpenClaw gateway listens on inside the agent container.
`OPENCLAW_GATEWAY_TOKEN`	No	auto-generated per agent	Static gateway token override. Most deployments rely on the per-agent token Nora issues.
`OPENCLAW_DOCKER_PACKAGE`	No	`openclaw@2026.6.11`	Validated package spec used across Docker, Kubernetes, and as the Proxmox fallback.
`OPENCLAW_TSX_BIN`	No	OpenClaw default	Path to the `tsx` runner inside the OpenClaw image.
`OPENCLAW_TSX_PACKAGE`	No	OpenClaw default	Override `tsx` package name.
`OPENCLAW_CLI_PATH`	No	OpenClaw default	Path to the OpenClaw CLI inside the image.
`OPENCLAW_DISABLE_BONJOUR`	No	`true`	Disable Bonjour/mDNS inside managed containers; set `0` only for deliberate LAN discovery.

When OPENCLAW_DOCKER_PACKAGE is overridden for NemoClaw, NEMOCLAW_SANDBOX_IMAGE must reference a prebuilt image containing the same exact OpenClaw version. The non-root NemoClaw runtime fails closed on a version mismatch instead of replacing the global package inside the sandbox.

Hermes runtime

Variable	Required	Default	Description
`HERMES_DOCKER_IMAGE`	No	Hermes default	Container image used for Hermes agents when `hermes` is in `ENABLED_RUNTIME_FAMILIES`.

Agent Hub source catalog

Configure where Agent Hub fetches community templates from. Internal templates are seeded automatically.

Variable	Required	Default	Description
`NORA_AGENT_HUB_URL`	No	`https://nora.solomontsao.com`	Base URL of the Agent Hub source catalog.
`NORA_AGENT_HUB_API_KEY`	No	—	API key for the source catalog. Stored encrypted in Admin Settings; the env value bootstraps the first run.

Workspace invitations

Variable	Required	Default	Description
`NORA_WORKSPACE_INVITE_SECRET`	No	—	Secret used to sign workspace invitation tokens. Falls back to `JWT_SECRET` when unset.

Integrations

Variable	Required	Default	Description
`NORA_INTEGRATIONS_DIR`	No	`backend-api/integrations-data`	Directory where integration runtime files are written before being mounted into agents.
`NORA_INTEGRATIONS_CONFIG`	No	—	Path to a JSON file overriding the default integration catalog.

Managed backups

NORA_BACKUP_STORAGE selects the destination. Supported values: local (default volume), s3, r2, ssh. Leave the destination credentials empty to manage them through Admin Settings instead of .env.

Variable	Required	Default	Description
`NORA_BACKUP_STORAGE`	No	`local`	Destination type. One of `local`, `s3`, `r2`, `ssh`.
`NORA_BACKUP_DIR`	No	—	Override path for `local` destination. Defaults to the `nora_backups` Docker volume.
`NORA_BACKUP_LIMIT_PER_AGENT`	No	`10`	Maximum number of retained backups per agent.
`NORA_BACKUP_STORAGE_MB`	No	`51200`	Soft cap on total backup storage in megabytes.
`NORA_BACKUP_RETENTION_DAYS`	No	`30`	Number of days to retain expired backups before pruning.

S3-compatible

Use NORA_BACKUP_STORAGE=s3 for AWS S3 or any S3-compatible service. Set NORA_BACKUP_S3_ENDPOINT for non-AWS providers.

Variable	Required	Default	Description
`NORA_BACKUP_S3_BUCKET`	No	—	S3 bucket name.
`NORA_BACKUP_S3_REGION`	No	—	AWS region or compatible region string.
`NORA_BACKUP_S3_ENDPOINT`	No	—	Custom endpoint for non-AWS providers.
`NORA_BACKUP_S3_ACCESS_KEY_ID`	No	—	Access key.
`NORA_BACKUP_S3_SECRET_ACCESS_KEY`	No	—	Secret access key.
`NORA_BACKUP_S3_SESSION_TOKEN`	No	—	Optional STS session token.

Cloudflare R2

Use NORA_BACKUP_STORAGE=r2. Set NORA_BACKUP_R2_ENDPOINT to your account endpoint, e.g. https://<account-id>.r2.cloudflarestorage.com.

Variable	Required	Default	Description
`NORA_BACKUP_R2_BUCKET`	No	—	R2 bucket name.
`NORA_BACKUP_R2_REGION`	No	—	Region.
`NORA_BACKUP_R2_ENDPOINT`	No	—	Account-specific R2 endpoint URL.
`NORA_BACKUP_R2_ACCESS_KEY_ID`	No	—	R2 access key.
`NORA_BACKUP_R2_SECRET_ACCESS_KEY`	No	—	R2 secret access key.
`NORA_BACKUP_R2_SESSION_TOKEN`	No	—	Optional session token.

SSH / SFTP

Use NORA_BACKUP_STORAGE=ssh.

Variable	Required	Default	Description
`NORA_BACKUP_SSH_HOST`	No	—	SSH host.
`NORA_BACKUP_SSH_PORT`	No	`22`	SSH port.
`NORA_BACKUP_SSH_USERNAME`	No	—	SSH user.
`NORA_BACKUP_SSH_REMOTE_PATH`	No	—	Remote path where backup archives are uploaded.
`NORA_BACKUP_SSH_PRIVATE_KEY`	No	—	PEM-encoded private key for SSH auth.
`NORA_BACKUP_SSH_PASSWORD`	No	—	Password fallback when key auth is not configured.

Security

Variable	Required	Default	Description
`CORS_ORIGINS`	No	`http://localhost:8080`	Comma-separated list of allowed CORS origins. Update to your public origin when Nora is exposed on a domain, for example `https://app.example.com`.

LLM key storage

Variable	Required	Default	Description
`KEY_STORAGE`	No	`database`	Where LLM provider keys are stored. `database` encrypts and persists keys in PostgreSQL. `env` reads keys from environment variables instead.
`MICROSOFT_FOUNDRY_API_KEY`	No	—	Foundry API key when using `KEY_STORAGE=env` or injecting provider credentials directly into a runtime.
`MICROSOFT_FOUNDRY_BASE_URL`	No	—	Per-resource Foundry endpoint, for example `https://<resource>.services.ai.azure.com/openai/v1/`. Required for Microsoft Foundry runtime registration.
`MICROSOFT_FOUNDRY_DEPLOYMENT`	No	—	Exact Azure deployment name to use as the runtime model, for example `gpt-5.5-1`. Deployment names are operator-defined and must not be shortened to `gpt-5.5`.
`MICROSOFT_FOUNDRY_API_VERSION`	No	—	Optional Foundry API version for classic Azure OpenAI endpoint shapes. Leave empty when using the OpenAI v1 GA path.

TLS

Optional; only relevant when nginx terminates TLS directly inside the stack.

Variable	Required	Default	Description
`TLS_CERT_PATH`	No	—	Path to the TLS certificate file on the host. Used when nginx is configured to terminate TLS.
`TLS_KEY_PATH`	No	—	Path to the TLS private key file on the host.

Marketing analytics

Optional privacy-light analytics for the public marketing site, powered by Plausible. Off by default — self-hosted deployments ship zero tracking unless NEXT_PUBLIC_ANALYTICS_DOMAIN is set at build time.

Variable	Required	Default	Description
`NEXT_PUBLIC_ANALYTICS_DOMAIN`	No	—	Plausible domain for the public marketing site. Empty (default) ships zero tracking.
`NEXT_PUBLIC_ANALYTICS_SRC`	No	`https://plausible.io/js/script.js`	Plausible script URL; point at a self-hosted Plausible instance if you run one.

Cost reporting

These optional rates drive the Cost dashboards. Nora estimates spend from token usage recorded by OpenClaw, Hermes, and future runtime chat paths.

Variable	Required	Default	Description
`COST_PER_1K_TOKENS`	No	`0.002`	Fallback LLM token cost when a per-model rate is unavailable or historical usage has no model data.
`COST_MODEL_RATES_JSON`	No	—	JSON object mapping model ids or `provider/model` ids to token rates.

Example:

COST_MODEL_RATES_JSON={"openai/gpt-5.5":{"input_per_1k":0.002,"output_per_1k":0.008},"claude-sonnet-4-5":{"input_per_1k":0.003,"output_per_1k":0.015},"flat-model":{"per_1k":0.004}}

Use input_per_1k and output_per_1k when Nora records prompt/completion token splits. Use per_1k for total-token-only pricing.

Legacy AWS backup variables

These variables are read by older platform-settings code paths for backward compatibility. New deployments should use the NORA_BACKUP_S3_* family above instead.

Variable	Required	Default	Description
`AWS_S3_BUCKET`	No	—	Legacy S3 bucket alias for backups.
`AWS_ACCESS_KEY_ID`	No	—	Legacy AWS access key ID.
`AWS_SECRET_ACCESS_KEY`	No	—	Legacy AWS secret access key.
`AWS_SESSION_TOKEN`	No	—	Legacy optional AWS STS session token.

​Nora environment variable reference

​Required

​Secret files

​Bootstrap admin account

​Database

​Redis and queue

​Access and URL

​API request rate limits

​Login abuse protection

​OAuth

​Public signup abuse protection

​Release tracking and upgrades

​System banner

​Platform mode

​Self-hosted resource limits

​Billing / Stripe

​Runtime selection

​Kubernetes registry and Compose mount helpers

​Docker agent published ports

​Gateway proxy SSRF guard

​Remote Docker safety and authorization

​Proxmox

​NemoClaw / NVIDIA

​OpenClaw runtime

​Hermes runtime

​Agent Hub source catalog

​Workspace invitations

​Integrations

​Managed backups

​S3-compatible

​Cloudflare R2

​SSH / SFTP

​Security

​LLM key storage

​TLS

​Marketing analytics

​Cost reporting

​Legacy AWS backup variables

Nora environment variable reference

Required

Secret files

Bootstrap admin account

Database

Redis and queue

Access and URL

API request rate limits

Login abuse protection

OAuth

Public signup abuse protection

Release tracking and upgrades

System banner

Platform mode

Self-hosted resource limits

Billing / Stripe

Runtime selection

Kubernetes registry and Compose mount helpers

Docker agent published ports

Gateway proxy SSRF guard

Remote Docker safety and authorization

Proxmox

NemoClaw / NVIDIA

OpenClaw runtime

Hermes runtime

Agent Hub source catalog

Workspace invitations

Integrations

Managed backups

S3-compatible

Cloudflare R2

SSH / SFTP

Security

LLM key storage

TLS

Marketing analytics

Cost reporting

Legacy AWS backup variables