Docs Self-hosting & operations
Self-hosting & operations
Configuration reference
Every environment variable a self-hosted Kumo.io reads — 134 of them — generated from the same registry the product uses to report its own configuration. Variables marked secret are never displayed in diagnostics, only their presence.
Applies to: Self-hosted134 variablesgenerated from the product
Variables by area
Most installations set only a handful: the database connection, the public URL, the secrets encryption key, and an email relay. Everything else has a working default.
CoreNetwork and URLsSign-in and sessionsBot protection and social sign-inSecrets and encryptionObject storage and backupsEmailLicensingConnecting to Kumo.ioIntegrationsProductSync pipelineTelemetry and error reportingCLI
Core · 16
| Variable | What it does | |
|---|---|---|
| ECS_CONTAINER_METADATA_URI | Older ECS agent spelling of ECS_CONTAINER_METADATA_URI_V4 (same use). | |
| ECS_CONTAINER_METADATA_URI_V4 | Injected by the ECS agent into every task (not Kumo.io config). Present → the updates page recommends a CloudFormation stack update (the Marketplace template). | |
| KUBERNETES_SERVICE_HOST | Injected by the kubelet into every pod (not Kumo.io config). Present → the updates page gives a neutral Kubernetes roll-out instruction (no Kumo.io Kubernetes driver yet). | |
| KUMO_APP_VERSION | Reported application version. | |
| KUMO_AWS_MARKETPLACE | '1' enables the AWS Marketplace lane — hosted usage metering AND the control-plane fulfillment rail; seller creds come from the task role's default SDK chain (us-east-1). | |
| KUMO_BACKEND | in-memory | postgres backend selection. | |
| KUMO_DEPLOYMENT_DRIVER | How this installation was deployed, STAMPED by `kumo deployment` into the compose file it renders (`compose`) — never operator-set. The appliance updates page follows it (`kumo deployment apply`, not a bare `docker compose pull`); absent → derived from the substrate signals below (resolveInstallationUpdateMethodFromEnv). | |
| KUMO_DIST_FLAVOR | Distribution flavor (local|self-hosted|hosted|oem) — the single descriptor for the CLI command surface, the security posture (local→dev, else→fail-closed production), and the metering / no-surveillance policy (only hosted meters). DETECTED from the distribution package the deployment was built from, which is AUTHORITATIVE inside a shipped image; this var is a DEV-CHECKOUT override only (ignored when a dist root is detected) and an unrecognized value throws at boot. | |
| KUMO_LOG_LEVEL | Minimum log level for the runtime logger (debug | info | warn | error); `--verbose` sets it to debug. Invalid values fall back to info. | |
| KUMO_PG_DSN | secret | Postgres DSN (carries the DB password). |
| KUMO_RELEASE_STAGE | Release-stage label (error reporting / telemetry). Explicitly setting it also enables that stage for Bugsnag egress (dev smoke tests). | |
| KUMO_STORAGE_CAPACITY_BYTES | Provisioned disk capacity for the storage fill gauge. | |
| KUMO_SYNC_REGIONS | Comma-separated region allowlist for in-process syncs (default: all). | |
| NODE_ENV | Node runtime optimisation flag; NOT a Kumo.io security-posture signal (posture is derived from KUMO_DIST_FLAVOR). | |
| NODE_OPTIONS | Node runtime flags. In hosted deploys this preloads the New Relic ESM loader + agent; unset elsewhere. | |
| VITEST | Test-runner signal (set by Vitest). With NODE_ENV=test it selects the `test` deployment profile ON A DEV CHECKOUT only — never inside a shipped image (deploy-tree detection wins). |
Network and URLs · 19
| Variable | What it does | |
|---|---|---|
| HTTP_PROXY | secret | Fallback outbound proxy when HTTPS_PROXY is unset (same agent, same rules). |
| HTTPS_PROXY | secret | Outbound proxy for provider SDK calls (benchmark X4). Set → one proxy-aware HTTPS agent (Node proxyEnv) is built at composition and given to every AWS SDK client; The lower-case spellings count too. Secret because a proxy URL may carry credentials. |
| KUMO_ADMIN_API_CORS_ORIGINS | Admin CORS allowlist (comma-sep; * reflects any origin). | |
| KUMO_ADMIN_API_PORT | Admin API listen port (default 9503). | |
| KUMO_ADMIN_WEB_URL | Admin web base URL (SAML/OIDC handoff target). | |
| KUMO_API_CORS_ORIGINS | Tenant CORS allowlist (comma-sep; * reflects any origin). | |
| KUMO_API_PORT | Tenant API listen port. | |
| KUMO_AWS_TRUST_ACCOUNT_ID | Override for the AWS account tenants' cross-account roles must trust (published to the SPA as `awsTrustAccountId`). Normally DERIVED by `kumo serve ui` from its own STS identity; set only when the UI runs outside the crawler's AWS account. 12 digits. | |
| KUMO_EMBED_FRAME_ANCESTORS | CSP frame-ancestors allowlist for embedding. | |
| KUMO_EXTERNAL_URL | Canonical public base URL; derives the OIDC/Social/admin-OIDC/Slack redirect URIs (falls back to request host). hosted/self-hosted-required. | |
| KUMO_METRICS_PORT | Prometheus metrics listen port. | |
| KUMO_REDIS_URL | Redis/ElastiCache URL for distributed HTTP rate limiting. Set on a horizontally-scaled hosted deployment so replicas share one budget; unset → in-process per-replica limiter. | |
| KUMO_SCHEDULER_HEALTH_PORT | Scheduler health-probe listen port. | |
| KUMO_SETUP_UI_ROOT | Override for the built onboarding-SPA dist the appliance serves at /setup. Normally DERIVED: the image ships it beside the product SPA, at <dirname KUMO_UI_ROOT>/setup-ui (/app/setup-ui). Set only for a dev checkout (scripts/dev-appliance.sh). | |
| KUMO_UI_PORT | Static UI listen port. | |
| KUMO_UI_ROOT | Static UI asset root directory. | |
| KUMO_WEBHOOK_EGRESS_GUARD | SSRF guard for outbound alert/report webhooks: auto (default; guarded in production-like deploys) | on (force) | off (disable — honored for self-hosted/dev to reach internal webhook receivers; REFUSED for hosted). | |
| KUMO_WORKER_HEALTH_PORT | Worker health-probe listen port. | |
| NO_PROXY | Hosts the outbound proxy is bypassed for (Node proxyEnv rules: comma-separated, leading-dot suffixes). Read only when HTTPS_PROXY/HTTP_PROXY is set. |
Sign-in and sessions · 10
| Variable | What it does | |
|---|---|---|
| KUMO_ADMIN_API_TOKENS | secret | Admin static bearer tokens. |
| KUMO_ADMIN_OIDC_CLIENT_ID | Admin-realm OIDC client id (enables admin OIDC login). | |
| KUMO_ADMIN_OIDC_CLIENT_SECRET | secret | Admin-realm OIDC client secret. |
| KUMO_ADMIN_OIDC_ISSUER | Admin-realm OIDC issuer URL. Callback derived from KUMO_EXTERNAL_URL / request host. | |
| KUMO_ADMIN_ROLES | Admin role assignments (fail-closed when absent). | |
| KUMO_API_TOKENS | secret | Tenant static bearer tokens (token:userId:accountId). |
| KUMO_DEV_ACCOUNT | DEV ONLY: the well-known dev account id that `kumo init` and dev-setup both provision into (default acct-dev). Single source of truth in config-diagnostics/devDefaults.ts; production names the account explicitly. | |
| KUMO_DEV_EMAIL | DEV ONLY: the well-known dev login email `kumo dev dataset bootstrap` and scripts/dev-setup.sh default to (default dev@kumo.local). Single source of truth in config-diagnostics/devDefaults.ts. | |
| KUMO_DEV_PASSWORD | secret | DEV ONLY: the dev login password `kumo dev dataset bootstrap` and scripts/dev-setup.sh default to. Never used by production entry points. |
| KUMO_HAVA_BRIDGE_PUBLIC_KEY | Ed25519 PUBLIC key (JWK `x`, base64url) that signs Hava switch assertions. Set = the /auth/hava bridge is live; unset = retired. Public half only — kumo can verify hava assertions, never mint them. Requires KUMO_EXTERNAL_URL. |
Bot protection and social sign-in · 7
| Variable | What it does | |
|---|---|---|
| KUMO_CAPTCHA_PROVIDER | CAPTCHA provider selector ('turnstile' default | 'recaptcha'); determines the siteverify endpoint. | |
| KUMO_CAPTCHA_SECRET | secret | CAPTCHA provider secret (enables the challenge when set). Read by the product server AND the account portal. |
| KUMO_CAPTCHA_SITE_KEY | CAPTCHA site key (public). | |
| KUMO_SOCIAL_OIDC_CLIENT_ID | Social-login OIDC client id. | |
| KUMO_SOCIAL_OIDC_CLIENT_SECRET | secret | Social-login OIDC client secret. |
| KUMO_SOCIAL_OIDC_ISSUER | Social-login OIDC issuer URL. | |
| KUMO_SOCIAL_OIDC_LABEL | Social-login button label. |
Secrets and encryption · 6
| Variable | What it does | |
|---|---|---|
| KUMO_AUDIT_CHECKPOINT_KEY | secret | HMAC key for signing audit integrity-chain segment checkpoints. Env wins; unset ⇒ self-provisioned once under KUMO_HOME/keys/audit-checkpoint.key (0600) on every profile except hosted (unset there ⇒ checkpoints unsigned, an attestation advisory) and test. |
| KUMO_AUTH_TOTP_KEY | secret | AES key for TOTP secret encryption. Env wins; unset ⇒ self-provisioned once under KUMO_HOME/keys/auth-totp.key (0600) on every profile except hosted (pods must share a secret-manager key — required there) and test. |
| KUMO_PG_SECRETS_KEK | secret | OPTIONAL base64 KEK for provider-credential envelope encryption (versioned form: KUMO_PG_SECRETS_KEK_<id>). Unset ⇒ a database-resident KEK is self-provisioned at boot (store always on); set it to hold the key OUTSIDE the database (stronger at-rest posture — hosted injects from Secrets Manager). |
| KUMO_PG_SECRETS_KEK_ID | Active KEK id (for rotation; default v1). | |
| KUMO_SAML_SP_PRIVATE_KEY | secret | SP private key for SAML encrypted-assertion decryption. |
| KUMO_WEBHOOK_SECRET_KEY | secret | AES-256-GCM key sealing outbound-webhook signing secrets at rest. Env wins; unset ⇒ self-provisioned once under KUMO_HOME/keys/webhook-secret.key (0600) on every profile except hosted (pods must share a secret-manager key — required there for webhooks) and test. The API (seals at create) and the delivery worker (unseals at drain) MUST share it. |
Object storage and backups · 17
| Variable | What it does | |
|---|---|---|
| KUMO_BACKUP_INTERVAL_HOURS | Scheduled-backup cadence in hours (default 24; 0 disables — manual backups only). | |
| KUMO_BACKUP_RETAIN_COUNT | Succeeded scheduled backups kept locally (default 7; manual/pre-upgrade never pruned). | |
| KUMO_BACKUP_S3_BUCKET | Off-box backup destination bucket (unset = local-only backups). | |
| KUMO_BACKUP_S3_ENDPOINT | Off-box backup S3-compatible endpoint (MinIO/R2). | |
| KUMO_BACKUP_S3_FORCE_PATH_STYLE | Path-style addressing for the backup destination. | |
| KUMO_BACKUP_S3_PREFIX | Off-box backup key prefix (default backups/). | |
| KUMO_BACKUP_S3_REGION | Off-box backup bucket region (SDK chain fallback). | |
| KUMO_OBJECT_STORE | inline | filesystem | s3 object-store backend (default inline). | |
| KUMO_OBJECT_STORE_DIR | Filesystem object-store directory. | |
| KUMO_S3_BUCKET | S3 bucket for artifacts / exports / bundles. | |
| KUMO_S3_ENDPOINT | S3 endpoint override (S3-compatible stores). | |
| KUMO_S3_FORCE_PATH_STYLE | Force path-style S3 addressing. | |
| KUMO_S3_KEY_PREFIX | Key prefix for stored objects. | |
| KUMO_S3_REGION | S3 region. | |
| KUMO_S3_SSE | S3 server-side-encryption mode. | |
| KUMO_S3_SSE_KMS_KEY_ID | KMS key id/ARN for S3 SSE-KMS (an identifier, not a secret). | |
| KUMO_S3_STORE_ID | Object-store id label. |
Email · 10
| Variable | What it does | |
|---|---|---|
| KUMO_EMAIL_API_SHAPE | Relay payload shape (json | sendgrid). | |
| KUMO_EMAIL_API_TOKEN | secret | Bearer token for the email relay. |
| KUMO_EMAIL_API_URL | HTTP-JSON email relay endpoint. | |
| KUMO_EMAIL_FROM | From address for outbound email. | |
| KUMO_EMAIL_SES_REGION | Region of the Amazon SES identity: sends through SES on the AWS SDK credential chain. Precedence: SMTP, then SES, then the HTTP relay. | |
| KUMO_SMTP_HOST | SMTP host (takes precedence over the HTTP relay). | |
| KUMO_SMTP_PASS | secret | SMTP auth password. |
| KUMO_SMTP_PORT | SMTP port. | |
| KUMO_SMTP_SECURE | SMTP TLS mode. | |
| KUMO_SMTP_USER | SMTP auth user. |
Licensing · 6
| Variable | What it does | |
|---|---|---|
| KUMO_INSTALLATION_ID | License installation binding: must match the signed license's subject.installationId when that claim is present (offline/air-gapped installs). Read ONLY by the license verifier — the agent's claimed ins_… identity is the platform identity. | |
| KUMO_LICENSE_ACTIVATION_FILE | Activation-receipt path, shared by the admin API + license CLI (default $KUMO_HOME/license-receipt.json). | |
| KUMO_LICENSE_EXPECTED_CUSTOMER_ID | Pin the license to a specific customer id. | |
| KUMO_LICENSE_FILE | Path to the license document. | |
| KUMO_LICENSE_TEXT | secret | Inline license document text. |
| KUMO_LICENSE_TRUST_BUNDLE_FILE | Path to the vendor trust-bundle. |
Connecting to Kumo.io · 5
| Variable | What it does | |
|---|---|---|
| KUMO_CONTROL_PLANE_BOOTSTRAP_URLS | Comma-separated bootstrap origins for the SIGNED service directory (default: the PERMANENT anchor https://bootstrap.kumo.io, or KUMO_CONTROL_PLANE_URL when that is explicitly set — ruled 2026-08-30, split-anchor: bootstrap.kumo.io serves ONLY the directory and never moves). Discovery failure never blocks local operation. | |
| KUMO_CONTROL_PLANE_URL | Bootstrap seed for hosted discovery (default https://connect.kumo.io — ruled 2026-08-30, split-anchor). Since the directory-driven gateway (same day) API calls follow the VERIFIED directory's services.api, so this only seeds where the directory is fetched from; setting it alone also moves the bootstrap default to the same host (dev standups). | |
| KUMO_ENTITLEMENT_TRUST_KEYS | JSON array of {keyId, publicKey} PUBLIC keys the agent trusts for kumo.license.v1 entitlement documents — publicKey as EITHER the base64url x string or the JWK object (same parser as KUMO_RELEASE_ROOT_KEYS). BAKED at build (CI BAKE_ENTITLEMENT_TRUST_KEYS variable); runtime env overrides; absent = fail-closed. | |
| KUMO_LOCAL_CONTROL_PORT | Loopback port of the local control server inside the appliance (default 9505; the UI proxy mounts it at /setup + /api/v1 on the product origin). | |
| KUMO_RELEASE_ROOT_KEYS | JSON array of {keyId, publicKey} release-root PUBLIC keys the agent trusts for signed service directories — publicKey as EITHER the base64url x string or the JWK object (one parser, both spellings, 2026-08-31). BAKED into shipped images at build (Dockerfile --build-arg / CI BAKE_RELEASE_ROOT_KEYS variable); runtime env overrides. Absent/empty = fail-closed (every directory refused). |
Integrations · 3
| Variable | What it does | |
|---|---|---|
| KUMO_SLACK_CLIENT_ID | Slack app client id (enables the Slack integration). | |
| KUMO_SLACK_CLIENT_SECRET | secret | Slack app client secret. |
| KUMO_SLACK_SIGNING_SECRET | secret | Slack request signing secret. |
Product · 2
| Variable | What it does | |
|---|---|---|
| KUMO_EXPORT_WATERMARK_TEXT | Export watermark text override. | |
| KUMO_REPORT_WEBHOOK_URLS | Report-delivery webhook registry: a JSON object mapping webhookId → https URL (e.g. {"ops":"https://hooks.example/x"}). Boot-parsed; malformed JSON fails startup. |
Sync pipeline · 4
| Variable | What it does | |
|---|---|---|
| AWS_DEFAULT_REGION | Standard AWS SDK alias of AWS_REGION (same use). | |
| AWS_REGION | STS region for EKS kubeconfig regeneration (`kumo source sync-batch --regen-eks`); `AWS_DEFAULT_REGION` is the standard-SDK alias. Boot-resolved into the resolver, never read per crawl. | |
| KUMO_AUTO_GRAPH_DIFF | Kill-switch for auto graph-diff on each WGR (worker + server roles default ON; =0 disables). Bare CLI/corpus compositions stay opt-in (=1). Feeds the sync→alerts chain. | |
| KUMO_PRESYNC_CREDENTIAL_HEALTH | Kill-switch for the pre-sync credential-health annotator (default ON when a real broker is wired; =0 disables — mirrors KUMO_AUTO_GRAPH_DIFF). |
Telemetry and error reporting · 6
| Variable | What it does | |
|---|---|---|
| BUGSNAG_API_KEY | secret | Bugsnag error-reporting key (server; un-prefixed). |
| KUMO_BUGSNAG_BROWSER_API_KEY | Bugsnag BROWSER notifier key, published to the co-served SPA in /config.json (public by design; separate project from the server key). Unset = browser error reporting off. | |
| KUMO_PG_DEBUG_SQL | '1' logs executed SQL (debug). | |
| NEW_RELIC_APP_NAME | New Relic application name; each runtime role appends its own suffix. | |
| NEW_RELIC_DISTRIBUTED_TRACING_ENABLED | 'true' links the roles' transactions into one distributed trace. | |
| NEW_RELIC_LICENSE_KEY | secret | New Relic ingest licence key. Unset = the APM agent sends nothing. Hosted images only. |
CLI · 23
| Variable | What it does | |
|---|---|---|
| INIT_CWD | pnpm-set invoking directory; the CLI resolves user-supplied relative paths against it when run through `pnpm kumo` (falls back to process.cwd()). | |
| KUMO_ACCOUNT | CLI active-account selector (id | name | @latest). | |
| KUMO_ADMIN_API_URL | CLI client admin-API base URL. | |
| KUMO_ALLOW_DESTRUCTIVE | '1' lets destructive CLI commands proceed without --yes (the non-local-DSN guard still applies). | |
| KUMO_API_TOKEN | secret | CLI client bearer for the tenant API (client-side). |
| KUMO_API_URL | CLI client tenant-API base URL (remote mode). | |
| KUMO_CONFIG_DIR | CLI config directory override. | |
| KUMO_CONTEXT_FILE | CLI context-store file path override. | |
| KUMO_CREDENTIAL | CLI selector default for --credential (`kumo use credential`), like KUMO_ACCOUNT / KUMO_WORKSPACE. | |
| KUMO_DATASET | CLI dataset selector; also stamped on dev error reports (runtime.dataset). | |
| KUMO_DEBUG | '1' enables verbose CLI debug output. | |
| KUMO_DEPLOYMENT_ACTOR | Actor label stamped into `kumo deployment` journal entries (default $USER). | |
| KUMO_ENVIRONMENT | CLI active-environment selector. | |
| KUMO_HOME | Kumo.io home directory (default ~/.kumo). | |
| KUMO_NO_CONTEXT | '1' disables the CLI context store. | |
| KUMO_RESET_ALLOW | =<dbname> | '*' allows destructive reset of a non-disposable-named database. | |
| KUMO_SECRET_MATERIAL | secret | `kumo source connect --secret-material-env`: the raw credential material to paste (never on argv). |
| KUMO_SHUTDOWN_TIMEOUT_MS | Graceful-shutdown drain deadline for served roles (positive integer ms; on timeout the process force-exits 1). | |
| KUMO_SIGNUP_INVITE_TOKEN | secret | `kumo auth signup` invite token (preferred over argv). |
| KUMO_SIGNUP_PASSWORD | secret | `kumo auth signup` password (preferred over argv). |
| KUMO_SOURCE | CLI active-source selector. | |
| KUMO_WGR | CLI active workspace-graph-revision selector. | |
| KUMO_WORKSPACE | CLI active-workspace selector. |