Skip to content

Reference

Configuration

Every environment variable this product reads, its default, and what it means. This is the complete list: a name missing from it is not part of the contract, no matter where you saw it. Source: CONTRACT.md and its addenda, and the configuration packages of each service (internal/config), which refuse to start on a value they cannot parse rather than fall back to a default.

Three scopes matter, and the tables below name one per row:

  • build-time: baked into an image at docker build time. Changing it on a running container does nothing; you must rebuild.
  • runtime: read from the process environment on startup (or, for a couple of backend-service values, cached with a bounded refresh). Changing it means restarting the container/pod, not rebuilding.
  • runtime, server-only: runtime, and never sent to a browser. This scope only exists on web; the Addendum v0.2 proxy exists to keep it there.

web

VarDefaultScopeMeaning
NEXT_PUBLIC_DEMO_MODEtruebuild-timeServe built-in demo data; the Orbit Deck needs no backend at all. next build inlines it into the browser bundle: set it with --build-arg, never at docker run/pod time.
PORT3000runtimeListen port for the Next.js standalone server.
NODE_ENVproductionruntimeStandard Node.js mode flag; the shipped image always runs production.
HOSTNAME0.0.0.0runtimeBind address for the standalone server: 0.0.0.0, so it's reachable from outside its own container/pod network namespace.
MALLOC_ARENA_MAX1 (set in the image)runtimeglibc malloc arenas for the Next.js server. One per thread held tens of MiB after a burst of traffic, and a pod limited to one core has no contention to avoid.
MALLOC_MMAP_THRESHOLD_65536 (set in the image)runtimeAllocations of at least this many bytes go straight to mmap, so freeing one returns it to the node. Setting it also stops glibc raising the threshold after the first large free.
ORBIT_API_URLhttp://orbit-api:8080 (compose) / templated to the in-cluster Service (Helm/kubectl)runtime, server-onlyBase URL the Next.js server uses to reach orbit-api. Never reaches the browser; see architecture.md.
ORBIT_AUTH_TOKENemptyruntime, server-onlyThe bearer web's server attaches to every proxied /api/* call. Read from a Secret; must match orbit-api's own ORBIT_AUTH_TOKEN.
WEB_AUTH_MODEemptyruntimebasic turns on web's own HTTP Basic auth in front of every route; empty or disabled leaves it off; any other value fails closed. See security.md.
WEB_AUTH_USERemptyruntime, server-onlyThe single user name web's Basic auth accepts; no colon. Required when WEB_AUTH_MODE=basic.
WEB_AUTH_VERIFIERemptyruntime, server-onlyA PBKDF2 verifier for the password (never the password itself), generated by node apps/web/scripts/hash-password.mjs. Required when WEB_AUTH_MODE=basic; see security.md.
WEB_TRUST_PROXYfalse; the plain manifests set true, and the chart derives it from ingress.enabled when emptyruntimetrue says an edge proxy in front of web writes X-Forwarded-For, and only then does web pass that header to orbit-api, which records the client address from it in the audit trail and keys its per-client limits on it. true with nothing in front of web lets a browser choose the address it is recorded under. See audit.md → "How the client IP is determined".
ORBIT_PUBLIC_URLempty; the chart sets it on web only from publicUrlruntimeThe address people open the Deck at. When it is https://..., web takes the browser to be on https whatever X-Forwarded-Proto says: __Host- cookies with Secure, and https:// in the MCP snippet and the SSO redirect URIs, whose host still comes from the request. It is for an edge that rewrites that header, such as an ingress with no TLS behind a CDN. Empty, http://... or unreadable, the header decides. An install that was reading http signs everyone in once more when this goes on, and a browser that reaches the Deck over plain http anywhere but localhost cannot keep the cookie. It encrypts nothing: see audit.md → "Behind a cloud load balancer or a CDN".
ORBIT_DECK_WRITE_TOKENemptyruntime, server-only, from Secret (key DECK_WRITE_TOKEN)The operator token a person types in the Deck before a scale or resources write (Addendum v0.4), compared on web's hop and never forwarded. Empty refuses every workload write with 403 writes_disabled.
ORBIT_DECK_OPERATORemptyruntimeA label, not a credential: the console name a workload write is logged under beside the signed-in user (console in the log line and the audit event).
ORBIT_DECK_WRITESemptyruntimesession: with no ORBIT_DECK_WRITE_TOKEN, a signed-in user's workloads.write (editor, admin) stands in for the operator token on the two workload writes; same-origin proof, the dry-run with its diff and the audit trail stay. orbit-api still needs ORBIT_WRITE_ENABLED and rbac.write.enabled. Empty keeps the token as the only way.
ORBIT_CLUSTER_IDemptyruntime, server-onlyLive mode only: the cluster the Deck opens when the address names none. Empty picks the first cluster orbit-api lists.

NEXT_PUBLIC_API_URL does not exist in this contract. It was removed in Addendum v0.2: a build-time, browser-inlined API URL was both a misleading knob (one image per API URL) and a documented route around the server-side proxy. If you see it in an older fork or a stale deployment, that deployment predates the addendum.

orbit-api

VarDefaultScopeMeaning
ORBIT_ADDR:8080runtimeListen address for the API.
ORBIT_LOG_LEVELinforuntimedebug | info | warn | error.
ORBIT_LOG_PROBESfalseruntimeLog /healthz, /readyz and /metrics requests at info; otherwise only at debug.
ORBIT_CORS_ORIGINShttp://localhost:3000runtimeComma-separated allowed origins. In the Helm chart, an empty value is derived from ingress.host + ingress.tls.enabled (https://sreorbit.example.com, never a scheme the ingress doesn't serve); set a literal only to add extra origins on top.
ORBIT_DEMO_DATAtrueruntimetrue = deterministic demo estate, no cluster access required, and on a first start with no user and no admin pair, the three demo accounts (identity.md). false = the live Kubernetes source, reading real clusters through ORBIT_KUBECONFIG or in-cluster credentials. ORBIT_AUTH_MODE=disabled is refused in this mode (below): an unauthenticated port onto a real cluster is not a local demo.
ORBIT_NOCTURNE_URLhttp://nocturne:8081runtimeBase URL for the internal reverse proxy to nocturne.
ORBIT_NOCTURNE_TOKENfalls back to NOCTURNE_AUTH_TOKENruntime, from SecretThe bearer the proxy attaches on its hop to nocturne. Either name works, so the two manifests cannot disagree.
ORBIT_STREAM_TIMEOUT180sruntimeHow long a proxied nocturne stream may run. Keep it above NOCTURNE_TIMEOUT plus 30s.
ORBIT_KUBECONFIGemptyruntimePath to a kubeconfig, read only when ORBIT_DEMO_DATA=false. Empty means in-cluster credentials, which needs the pod's ServiceAccount token projected and a role bound to it: components.orbit-api.rbac.enabled in the chart, deploy/kubectl/15-rbac-orbit-api.yaml in the plain manifests. When a path is given, every context in the file becomes one cluster and the {id} in /api/v1/clusters/{id} is that context name lowercased with every character outside [a-z0-9-] replaced by - (an EKS ARN becomes arn-aws-eks-us-east-1-...). Two contexts that sanitise to the same id is a startup failure. Mount the file as a volume; never paste one into an env var or a manifest.
ORBIT_CLUSTER_IDlocalruntimeThe {id} of the cluster orbit-api is running inside, used only when ORBIT_KUBECONFIG is empty, because an in-cluster pod has no context name to derive one from. Must match [a-z0-9-]{1,128}; anything else refuses to start.
ORBIT_CLUSTER_NAMEORBIT_CLUSTER_IDruntimeDisplay name for that cluster. Cosmetic.
ORBIT_STACK_URLemptyruntimeBase URL of a Prometheus-compatible HTTP API (orbit-stack) backing GET /api/v1/query_range, the dashboards' label and series reads, and every APM route. Empty: query_range answers an empty series carrying the right unit, an ad-hoc PromQL expression (every dashboard panel is one) is refused with invalid_request, the APM and metadata routes answer 503 not_ready, and /readyz does not check it. Set: ad-hoc PromQL runs on the engine on demo data too, and /readyz also checks its /healthz, so orbit-api is NotReady until the engine answers. In the Helm chart an empty value is derived to http://<fullname>-orbit-stack.<namespace>.svc.cluster.local:8082, the same way ORBIT_NOCTURNE_URL is.
ORBIT_STACK_TOKENemptyruntime, from SecretBearer attached to every ORBIT_STACK_URL call. Optional: the engine may need none. Setting it while ORBIT_STACK_URL is empty refuses to start, because nothing would carry it. Redacted in every log line.
ORBIT_USAGE_SOURCEautoruntimeWhere live CPU and memory usage comes from. auto: metrics.k8s.io while the cluster serves it, the engine when it does not. orbit-stack: the engine always, which needs ORBIT_STACK_URL.
ORBIT_CACHE_MAX_AGE90sruntimeHow long the live source's informer cache may go without its watches making progress before /readyz names it stale in its cache rows. A cache that has filled keeps serving, and the pod stays ready, while it is stale; only a cache that has not filled yet, or an API server that does not answer, makes /readyz answer 503. Widen it for a slow or busy API server.
ORBIT_WRITE_ENABLEDfalseruntimetrue lets the scale and resources routes change the cluster (Addendum v0.4), together with the write ClusterRole the chart renders only for components.orbit-api.rbac.write.enabled. Anything but true answers 403 writes_disabled.
ORBIT_SECRETS_READfalseruntimetrue lets the configuration view read the Secrets a workload's template references, with the get on secrets (never list or watch) the chart grants only for components.orbit-api.rbac.secrets.enabled (Addendum v0.11). Off, a Secret reference reads not-read and its value cannot be revealed. The chart sets it from that same value, on the pod; components.orbit-api.env refuses it.
ORBIT_KARPENTER_NAMESPACEkarpenterruntimeWhere Karpenter runs. FinOps prices each node from Karpenter's AWS estimates (on-demand and spot, by zone), read every 10 minutes from its pods' http-metrics port; the chart's NetworkPolicy opens that port alone, and only when the namespace exists. none reads nothing: the embedded list prices alone.
ORBIT_NODE_HOURLY_USD0runtimeUSD per hour for a node whose instance type is not in orbit-api's embedded on-demand price list (see architecture.md → live mode). Any non-EC2 node, k3s included, lands here. 0 counts such a node as free, which surfaces as an implausibly small bill rather than an invented one. Must be a non-negative number.
ORBIT_RECOMMENDATIONS_REFRESH5mruntimeHow often the Deck's recommendations are recomputed in the background, per cluster; requests get the last result, so a recommendation is at most one interval old. A failed run is not served: the next request computes again. 0 computes on every request, as the Go original (tag go-oracle) did. Anything but 0 or a Go duration of 1s or more refuses to start.
ORBIT_TRUSTED_PROXIESemptyruntimeComma-separated CIDRs (or single addresses) of proxies between web and orbit-api whose X-Forwarded-For is believed: a mesh sidecar, an internal gateway. Not web itself: a request carrying orbit-api's own bearer is web's, and its X-Forwarded-For is already believed (Addendum v0.5). The client address, for the audit trail and every per-client limit, is the nearest hop in that header not on this list. Empty is right for every shipped install path; a pod CIDR here would also skip the ingress's own address. An entry that is not an address refuses to start.
ORBIT_SHUTDOWN_GRACE180sruntimeGraceful-shutdown budget, matched to nocturne's so a proxied answer (up to 150s of streaming) is allowed to finish; any proxied stream still open 5s before the budget ends is closed with an event: done frame carrying finishReason: "shutdown". Must stay below the pod/container's own termination grace period (200s in every shipped manifest) or SIGKILL wins the race; see operations.md. (CONTRACT.md's base table says 15s; the addendum and the shipped defaults supersede it.)
ORBIT_AUTH_MODEstaticruntimestatic | oidc | disabled. See "Auth modes" below.
ORBIT_AUTH_TOKENemptyruntime, from SecretRequired, ≥32 bytes, when mode is static. The service refuses to start otherwise.
ORBIT_OIDC_ISSUERemptyruntimeRequired when mode is oidc.
ORBIT_OIDC_AUDIENCEemptyruntimeRequired when mode is oidc.
ORBIT_METRICS_ADDR:9090runtimeSeparate listener for /metrics (Addendum v0.2). Never the API listener; never routed by an ingress.
ORBIT_CONTACT_WEBHOOK_URLemptyruntime, from SecretOptional. Every lead the site's contact form stores (under ORBIT_DATA_DIR/leads, listed at /deck/admin/leads) is also POSTed here as JSON, retried in the background three times; a failure is logged and loses nothing. A webhook URL usually carries its token: never logged, never in a committed file. With NetworkPolicy on, orbit-api also needs components.orbit-api.networkPolicy.allowInternetEgress.

Identity (Addendum v0.5)

VarDefaultScopeMeaning
ORBIT_DATA_DIR/var/lib/sreorbitruntimeUsers, roles, sessions, dashboards, alert acknowledgements, leads and the audit trail, as files. Must be writable, or orbit-api refuses to start. One writer: run one replica. A PVC in the chart with components.orbit-api.persistence.enabled (keep mountPath equal to this), an emptyDir otherwise, the named volume orbit-api-data on compose. See identity.md → "Where the state lives".
ORBIT_SESSION_SECRETemptyruntime, from SecretHMAC key that signs session tokens, 32 bytes or more (openssl rand -base64 48); shorter refuses to start. Empty: a 32-byte key is generated once into ORBIT_DATA_DIR/session.key. Changing it ends every session. Set it when backups of the data directory must not carry the signing key.
ORBIT_ADMIN_USERemptyruntime, from SecretThe first admin's username, created at startup only when no user exists; ignored afterwards. Lowercased, then [a-z0-9][a-z0-9._-]{0,31}. Set together with the next one or neither: one alone refuses to start.
ORBIT_ADMIN_PASSWORD_VERIFIERemptyruntime, from SecretThat admin's password as a PBKDF2 verifier (node apps/web/scripts/hash-password.mjs < admin-password), never the password. A malformed one refuses to start.
ORBIT_AUDIT_RETENTION90druntimeHow long the audit trail keeps a day: days (90d, 365d) or a Go duration of 24h or more. See audit.md.
ORBIT_CHAT_RETENTION5druntimeHow long a Nocturne conversation is kept after its last message: days (5d) or a Go duration from 1h to 90d. An hourly sweep deletes expired ones from disk, including those of users who never sign in again.

Single sign-on seeds (Addenda v0.8 and v0.19)

Both providers are normally set up in the console, at Admin > Integrations. These variables seed one only while the store holds no settings document for it; the first save in the console wins from then on. Unset, the provider is off. See identity.md → "Single sign-on".

VarDefaultScopeMeaning
ORBIT_SSO_GOOGLE_CLIENT_IDemptyruntimeGoogle's Web application client ID, <digits>-<id>.apps.googleusercontent.com. Set with the next two, or none of the three: anything in between refuses to start.
ORBIT_SSO_GOOGLE_CLIENT_SECRETemptyruntime, from SecretIts client secret. Never logged, never answered by a read.
ORBIT_SSO_ALLOWED_DOMAINSemptyruntimeThe Workspace domains Google sign-in accepts, comma-separated; gmail.com is refused.
ORBIT_SSO_DEFAULT_ROLEviewerruntimeThe role of a first Google sign-in: viewer or editor.
ORBIT_SSO_OIDC_ISSUERemptyruntimeThe OpenID Connect provider's issuer, https, exactly as its discovery document names it. Set with the next two, or none of the three: anything in between refuses to start, and so does any other ORBIT_SSO_OIDC_* without them.
ORBIT_SSO_OIDC_CLIENT_IDemptyruntimeThe client ID at that provider.
ORBIT_SSO_OIDC_CLIENT_SECRETemptyruntime, from SecretIts client secret (secrets.ssoOidcClientSecret in the chart). Never logged, never answered by a read.
ORBIT_SSO_OIDC_DISPLAY_NAMESSOruntimeThe name on the button, "Sign in with ...", and the provider's name in the audit trail. 40 characters at most.
ORBIT_SSO_OIDC_SCOPESopenid email profileruntimeSpace-separated; must include openid.
ORBIT_SSO_OIDC_ALLOWED_DOMAINSemptyruntimeEmail domains allowed in, comma-separated. Empty allows any address the provider vouches for.
ORBIT_SSO_OIDC_EMAIL_CLAIMemailruntimeThe top-level ID-token claim holding the address.
ORBIT_SSO_OIDC_GROUPS_CLAIMgroupsruntimeThe top-level ID-token claim holding the groups.
ORBIT_SSO_OIDC_GROUP_ROLESemptyruntimegroup=role pairs separated by ; or new lines, in order, the first match winning; each is split at its last =, so an LDAP DN works as a group. A role that does not exist refuses that person's sign-in (role_missing).
ORBIT_SSO_OIDC_DEFAULT_ROLEviewerruntimeThe role of anyone no group maps: viewer, editor or deny. deny needs at least one mapped group.
SSL_CERT_FILEunsetruntimeA PEM bundle orbit-api trusts instead of the image's roots, for a provider behind a private CA. Include the public roots in it when Google or a hosted provider must still verify.

nocturne

VarDefaultScopeMeaning
NOCTURNE_ADDR:8081runtimeListen address for the API.
NOCTURNE_LOG_LEVELinforuntimeLog level.
NOCTURNE_LOG_PROBESfalseruntimeLog probe and /metrics requests at info.
NOCTURNE_PROVIDERmockruntimemock | openai | openai-responses | anthropic. mock needs no credential and makes no outbound call, so the demo runs dry. openai-responses is OpenAI's Responses API: reasoning effort up to max, the model's reasoning carried across tool turns, store=false. anthropic is the Messages API (e.g. claude-sonnet-5-5): a set effort turns on adaptive thinking, thinking blocks go back with their signature across tool turns, tools and system prompt are cached across chats and the conversation tail across tool steps, and on the Claude API a refusal is retried on Anthropic's default fallback model (beta server-side-fallback-2026-07-01). A refusal ends the answer with finish refusal.
NOCTURNE_BASE_URLemptyruntimeOpenAI-compatible base URL, e.g. https://api.openai.com/v1. Required when provider is openai or openai-responses.
NOCTURNE_API_KEYemptyruntime, from SecretProvider credential. Never logged. Empty is valid when provider is mock.
NOCTURNE_REASONING_MODELemptyruntimeModel id for the reasoning tier (analysis, root cause, FinOps plans).
NOCTURNE_FAST_MODELemptyruntimeModel id for the fast tier (product help, short answers).
NOCTURNE_REASONING_EFFORTemptyruntimeReasoning effort of the reasoning tier: none | minimal | low | medium | high | xhigh | max. Empty sends none. Which values a model takes is the provider's answer (chat completions stops at xhigh). With anthropic, none and minimal send low.
NOCTURNE_FAST_EFFORTemptyruntimeThe same for the fast tier.
NOCTURNE_MAX_TOKENS2048runtimeResponse ceiling, reasoning tokens included: raise it with a high effort.
NOCTURNE_TIMEOUT120sruntimeUpstream provider timeout. The stream's write deadline is this plus 30s, so raise ORBIT_STREAM_TIMEOUT above both.
NOCTURNE_TRIAGE_URLemptyruntimeSystem 1: a typed classifier (POST /v1/systemone, TypeSafe's Jev API) that routes the questions the keywords miss and ranks the health sweep an outage question opens with. Empty turns it off.
NOCTURNE_TRIAGE_API_KEYemptyruntime, from SecretIts credential. Required with the URL. Never logged.
NOCTURNE_TRIAGE_MODELemptyruntimeIts model id, e.g. a pinned version. Required with the URL.
NOCTURNE_ORBIT_URLemptyruntimeorbit-api's base URL, which the cluster tools read. Empty runs the assistant with no tools.
NOCTURNE_ORBIT_TOKENfalls back to ORBIT_AUTH_TOKENruntime, from SecretThe bearer the tools present to orbit-api, beside the asking user's session. Never logged.
NOCTURNE_TOOL_TIMEOUT10sruntimeOne tool call, orbit-api included. Longer than NOCTURNE_TIMEOUT refuses to start.
NOCTURNE_MAX_TOOL_STEPS6runtimeModel turns that may call tools in one answer, 1 to 20.
NOCTURNE_TOOL_MAX_BYTES8000runtimeThe most of one tool result the model reads, 1024 to 65536 bytes.
NOCTURNE_TRUSTED_PROXIESemptyruntimeSame semantics as ORBIT_TRUSTED_PROXIES. orbit-api is nocturne's only peer and forwards the chain it saw, so name the same CIDR here.
NOCTURNE_AUTH_MODEstaticruntimeSame semantics as ORBIT_AUTH_MODE. nocturne is reachable only through orbit-api on the network, but "unreachable" is a network control, not an authentication one, and it's the component that carries model spend.
NOCTURNE_AUTH_TOKENemptyruntime, from SecretRequired, ≥32 bytes, when mode is static.
NOCTURNE_OIDC_ISSUERemptyruntimeRequired when mode is oidc.
NOCTURNE_OIDC_AUDIENCEemptyruntimeRequired when mode is oidc.
NOCTURNE_METRICS_ADDR:9090runtimeSeparate listener for /metrics (Addendum v0.2).
NOCTURNE_SHUTDOWN_GRACE180sruntimeGraceful-shutdown budget, the same as orbit-api's, so an in-flight SSE stream has time to drain. A drain overrun logs shutdown incomplete and exits 0; it is never reported as a startup failure.
ORBIT_DEMO_DATAtrueruntimeRead by nocturne too, with the same meaning as on orbit-api: false refuses NOCTURNE_AUTH_MODE=disabled.

orbit-stack

The Helm chart sets ORBIT_STACK_QUERY_RPM to 60000 and ORBIT_STACK_QUERY_BURST to 3000: every Deck viewer reads through orbit-api, one client address, and a 30-day traces page is about a hundred reads.

Every variable of the telemetry engine, with its default and meaning, is in orbit-stack.md so the engine's page stays self-contained: ORBIT_STACK_ADDR (:8082), ORBIT_STACK_METRICS_ADDR (:9090), ORBIT_STACK_LOG_LEVEL, ORBIT_STACK_LOG_PROBES, ORBIT_STACK_DATA_DIR (/data, a volume), ORBIT_STACK_RETENTION (15d), ORBIT_STACK_BLOCK_DURATION (2h), ORBIT_STACK_COMPRESSION (better), ORBIT_STACK_BLOCK_CACHE_BYTES, ORBIT_STACK_HEAD_CHUNK_SAMPLES (120), ORBIT_STACK_MAX_SERIES (0), ORBIT_STACK_MAX_LABELS_PER_SERIES (64), ORBIT_STACK_MAX_LABEL_NAME_LEN (256), ORBIT_STACK_MAX_LABEL_VALUE_LEN (4096), ORBIT_STACK_MAX_INDEX_BYTES, ORBIT_STACK_QUERY_TIMEOUT (30s), ORBIT_STACK_QUERY_MAX_SAMPLES, ORBIT_STACK_QUERY_TURNS (0), ORBIT_STACK_QUERY_RPM (3000), ORBIT_STACK_QUERY_BURST (300), ORBIT_STACK_MAX_BODY_BYTES, ORBIT_STACK_AUTH_MODE (static), ORBIT_STACK_AUTH_TOKEN (from Secret, ≥ 32 bytes), ORBIT_STACK_TRUSTED_PROXIES, ORBIT_STACK_SHUTDOWN_GRACE (30s), and for traces ORBIT_STACK_TRACE_RETENTION (7d), ORBIT_STACK_TRACE_HEAD_BYTES (64MiB) and ORBIT_STACK_TRACE_MAX_BYTES (5MiB, one trace; spans past it are refused) and ORBIT_STACK_TRACE_GRAPH_PENDING (100000, service-graph spans waiting for their pair), which apm.md explains. orbit-api reaches it with ORBIT_STACK_URL and ORBIT_STACK_TOKEN (the same Secret key, ORBIT_STACK_AUTH_TOKEN, read under a second name, like ORBIT_NOCTURNE_TOKEN).

orbit-shop, the demo shop

The synthetic services that give APM real traces (apm.md → "The demo shop"), shipped in the orbit-stack image as /orbit-shop. Not part of a production install.

Var or flagDefaultMeaning
ORBIT_SHOP_OTLPempty, requiredThe engine's base URL, http://orbit-stack:8082; spans go to its /v1/traces.
ORBIT_SHOP_OTLP_TOKENemptyThe engine's bearer, ORBIT_STACK_AUTH_TOKEN, when its auth is static.
ORBIT_SHOP_URL_<SERVICE>emptyIn --service mode, where each other service answers: ORBIT_SHOP_URL_API_GATEWAY, ORBIT_SHOP_URL_CATALOG, and so on, the name upper-cased with - as _.
POD_NAME, POD_NAMESPACE, NODE_NAMEthe service name, shop, unknownThe span resource, from the downward API.
PORT8080The listen port in --service mode.
--all / --service NAMEnoneEvery service in one process on 127.0.0.1 from --port-base (default 18110), or one service (loadgen for the load alone). Exactly one of the two.
--rps5Requests a second the load generator sends, 0 to 1000. Compose reads it from ORBIT_SHOP_RPS, the chart from demo.shop.rps.

Auth modes

Set with ORBIT_AUTH_MODE / NOCTURNE_AUTH_MODE, independently per service (in practice, run both the same way):

ModeWhen to use itWhat it needs
static (default)Single shared credential, the common case for a self-hosted install.ORBIT_AUTH_TOKEN / NOCTURNE_AUTH_TOKEN, ≥32 bytes.
oidcYou already run an identity provider and want per-caller identity instead of a shared secret.<PREFIX>_OIDC_ISSUER and <PREFIX>_OIDC_AUDIENCE; the issuer's JWKS must be reachable from the pod.
disabledA laptop demo only.Nothing, and it must stay that way. Refused outright when ORBIT_DEMO_DATA=false, so it cannot be left on against a real cluster by accident.

Generating a static token

ORBIT_AUTH_TOKEN and NOCTURNE_AUTH_TOKEN are shared bearers you generate; nothing in this repository ships one. The requirement is "≥32 bytes"; the command below produces a 64-character hex string (32 bytes of real entropy, hex-encoded so it never needs shell-quoting):

bash
openssl rand -hex 32

Run it three times: orbit-api, nocturne and orbit-stack each need their own token, and web needs a copy of orbit-api's (it's the bearer web's server attaches when it proxies /api/*). Where each one goes depends on the install path; see the "Secrets" section of install/docker-compose.md, install/helm.md, or install/kubectl.md.

Two optional secrets belong to identity, not to a service hop: ORBIT_SESSION_SECRET (openssl rand -base64 48) and the first admin's verifier, which identity.md → "The first admin" generates.

Never commit a generated token. Never put one in a values file, a ConfigMap, or a ChartYAML default. CONTRACT.md: "Secrets are referenced, never embedded in a chart default."

demo vs live: two different flags

NEXT_PUBLIC_DEMO_MODE (on web, build-time) and ORBIT_DEMO_DATA (on orbit-api, runtime) look like the same switch and are not:

  • NEXT_PUBLIC_DEMO_MODE=true means the Orbit Deck UI reads its own synthetic data (apps/web/src/lib/demo-estate.ts) directly, without ever calling orbit-api.
  • ORBIT_DEMO_DATA=true means orbit-api itself serves a deterministic demo estate instead of querying a live cluster, independent of whether anything is calling it, and creates the three demo accounts on a first start with no user. false selects the live source (services/rust/orbit-api/src/live.rs), which needs credentials for at least one cluster (see ORBIT_KUBECONFIG) and refuses to start without them.

Setting one without the other is a valid but confusing configuration (web never calls orbit-api regardless of what orbit-api would have returned). Set them together. See architecture.md → "The data path for a metric, ingest to pixel" for exactly what each combination does.

Ports, all four components, one table

ComponentAPI portMetrics portExposed by default ingress?
web3000none (Next.js serves no /metrics)Yes, the only one
orbit-api80809090No (proxied through web)
nocturne80819090No (proxied through orbit-api; no ingress rule exists for it at all)
orbit-stack80829090No (queried by orbit-api; written to by in-cluster agents; no ingress rule)

Where to go next

  • What each auth mode's failure mode looks like in practice, and the threat model behind these defaults: security.md.
  • The exact command sequence that consumes these variables for your install path: install/README.md.