Skip to content

Overview

Architecture

SRE Orbit runs as four components with one auth boundary and one browser-facing surface. Every other page assumes you've read this one.

The four components

ComponentLanguageImageContainer port(s)Purpose
webTypeScript, Next.js 16 (standalone)ghcr.io/sreorbit/web:0.1.03000Marketing site + Orbit Deck UI. The only component an ingress ever routes to.
orbit-apiRustghcr.io/sreorbit/orbit-api:0.1.08080 (API), 9090 (metrics)Deck BFF: clusters, workloads, telemetry, FinOps; users, roles, sessions, dashboards and the audit trail, on its own volume, as one replica. Also the reverse proxy in front of nocturne.
nocturneRustghcr.io/sreorbit/nocturne:0.1.08081 (API), 9090 (metrics)AI assistant. Provider-abstract, streams over SSE. Never reachable from outside the cluster network.
orbit-stackRustghcr.io/sreorbit/orbit-stack:0.1.08082 (API), 9090 (metrics)The telemetry engine: Prometheus remote-write and OTLP traces in, PromQL and trace reads out, columnar zstd blocks and trace segments on a volume. orbit-api queries it; your agents and SDKs push into it. Never routed by an ingress.

Kubernetes namespace: sreorbit. Helm chart: deploy/helm/sreorbit. k3d dev cluster: sreorbit-dev. All four ship as multi-stage, distroless (nodejs26-debian13:nonroot for web; cc-debian13:nonroot for the three Rust services) images: no shell, no package manager, no curl in the final layer, non-root USER 65532:65532.

Orbit Stack is the name of the engine, orbit-stack is its container. The "one binary" line in the marketing copy refers to that engine, never to the platform, which is these four containers. What the engine stores, its endpoints and the PromQL it answers are in orbit-stack.md; what it measured against Prometheus is in benchmark.md.

What talks to what

text
                          Internet
                             │
                             ▼
                  ┌───────────────────────┐
                  │  Ingress / LB (yours) │   routes ONLY to web:3000
                  └───────────┬───────────┘
                              │ HTTPS
                              ▼
                  ┌───────────────────────┐        demo mode: synthetic data
                  │  web · Next.js :3000  │        generated in-process, zero
                  │  marketing + Deck UI  │◄─────── network hop (see below)
                  └───────────┬───────────┘
                              │ /api/*: the Next.js SERVER attaches
                              │ ORBIT_AUTH_TOKEN and forwards.
                              │ This hop never executes in the browser.
                              ▼
                  ┌───────────────────────┐
                  │ orbit-api · Rust :8080│───▶ :9090  /metrics (own listener,
                  │ clusters / workloads /│      own NetworkPolicy rule)
                  │ telemetry / FinOps    │───▶ orbit-stack :8082, PromQL for
                  └───────────┬───────────┘     query_range (ORBIT_STACK_URL)
                              │                        ▲ remote-write from the
                              │                        │ agents you run (or the
                              │                        │ k3d loop's telemetry feed)
                              │ POST /api/v1/nocturne/{chat,analyze,models}
                              │ streaming reverse proxy, NOCTURNE_AUTH_TOKEN
                              │ attached, SSE relayed unbuffered
                              ▼
                  ┌───────────────────────┐
                  │ nocturne · Rust :8081 │───▶ :9090  /metrics (own listener)
                  │ AI assistant, SSE     │
                  └───────────┬───────────┘
                              │ only when NOCTURNE_PROVIDER != mock,
                              │ and only with egress explicitly allow-listed
                              ▼
                   Model provider (OpenAI- or Anthropic-compatible)
                   (never contacted by the default install)

Three rules follow from that diagram, and the rest of this documentation depends on them:

  1. The browser never talks to orbit-api or nocturne directly. web is the only component with ingress.enabled: true in the Helm chart, the only one with a path in deploy/kubectl/60-ingress.yaml, and the only one docker-compose exposes for anything other than local debugging. NEXT_PUBLIC_API_URL does not exist in this contract: a build-time, browser-inlined API URL was both a misleading knob and a documented way around the proxy, so it's gone. web's Next.js server proxies /api/* to orbit-api and attaches ORBIT_AUTH_TOKEN itself; the token never reaches client JavaScript.
  2. nocturne has no public surface at all. It has no ingress rule, no CORS configuration, and (in Kubernetes) a NetworkPolicy that admits traffic from orbit-api only. orbit-api exposes POST /api/v1/nocturne/chat, POST /api/v1/nocturne/analyze and GET /api/v1/nocturne/models as a streaming reverse proxy to nocturne, attaching NOCTURNE_AUTH_TOKEN on that internal hop. An LLM endpoint reachable from the internet lets anyone who finds the URL run up your model bill; see security.md.
  3. /metrics is not part of the public API surface on either backend service. It binds a separate address (ORBIT_METRICS_ADDR / NOCTURNE_METRICS_ADDR, default :9090) that no ingress routes to and that the auth middleware's exemption list does not cover, because it isn't on the listener the exemption list applies to. In Kubernetes, reaching it from outside the pod at all requires a NetworkPolicy rule naming your Prometheus namespace explicitly; see security.md and operations.md.

The auth boundary

Every request into orbit-api or nocturne passes through one auth middleware ahead of the router, on the API listener only. Three modes (ORBIT_AUTH_MODE / NOCTURNE_AUTH_MODE):

  • static: constant-time comparison of Authorization: Bearer <token> against ORBIT_AUTH_TOKEN / NOCTURNE_AUTH_TOKEN. The service refuses to start if the token is empty or shorter than 32 bytes. This is the default.
  • oidc: an RS256/ES256 JWT verified against <PREFIX>_OIDC_ISSUER's JWKS, checking exp/iss/aud, with a bounded key-refresh cache.
  • disabled: local demos only. The service logs a WARN naming the risk on every startup, and refuses to start if ORBIT_DEMO_DATA=false, so you cannot run auth-disabled against a real cluster by accident.

GET /healthz and GET /readyz are exempt on every mode, on every service, always: a load balancer has to be able to probe a service before that service can prove it holds a valid credential for anything. Nothing else is exempt. A failed check returns 401 with {"error":{"code":"unauthorized","message":"..."}} and never distinguishes "no token", "wrong token", and "expired token" in that message; security.md explains why that's deliberate.

/metrics sits outside this boundary entirely, in the other direction: it is on a different listener than the one the auth middleware guards, so the exemption list doesn't apply to it: there is nothing to exempt it from. Its isolation is a network control (bind address + NetworkPolicy), not an auth one.

The boundary in one sentence: only web's server-rendered code and Next.js server functions ever hold ORBIT_AUTH_TOKEN or NOCTURNE_AUTH_TOKEN; nothing running in the browser, and no component other than web, ever does.

Who is asking: users on top of the bearer

The bearer proves a call came through web; it does not say which person is behind it. Addendum v0.5 adds that layer, and every piece of it lives in orbit-api:

  • The browser signs in through web's own route, which receives an opaque session token from orbit-api and keeps it in the HttpOnly cookie orbit_session. Page JavaScript never sees it.
  • On every proxied call and every server-side read, web copies that value into X-Orbit-Session beside the bearer, and never forwards the browser's Cookie header.
  • orbit-api checks the bearer, then the session (its signature, then that it exists, has not expired and belongs to an enabled user), then the one permission the route asks for, read from the user's role on that request. A route nobody gave a permission to is still session-gated: the public list is the probes, the sign-in routes and contact.
  • When someone asks Nocturne a question, their session rides along to nocturne and back into every tool call, so the assistant reads with their permissions and not the service's.

The roles, the closed permission set and the sign-in rules are in identity.md; what each change leaves behind is in audit.md.

The one piece of state orbit-api keeps

Users, roles, sessions, saved dashboards, alert acknowledgements, contact-form leads and the audit trail are files under ORBIT_DATA_DIR: one JSON document per object, written to a temporary file, fsynced and renamed, and the audit trail as one append-only JSONL file per day. A file store has one writer, so orbit-api runs as one replica on every install path: the chart renders replicas: 1 whatever replicaCount says, refuses autoscaling for it, drops its PodDisruptionBudget, and with persistence on puts the directory on a ReadWriteOnce claim with a Recreate rollout. That is the ceiling of this release: a rollout or a node loss is a short gap in the console, and orbit-api scales up, not out. The upgrade path the source names is Postgres. Everything else the Deck shows is still read live, from Kubernetes and the engine, and never stored here.

Traces: OTLP into the engine

Applications, or an OpenTelemetry Collector in front of them, send spans over OTLP/HTTP to orbit-stack on 8082 at /v1/traces, with the same bearer agents use for remote-write. The engine writes them to a trace log and an in-memory head, cuts the head into checksummed, compressed segments on its volume, and deletes whole segments after ORBIT_STACK_TRACE_RETENTION. Every accepted span also feeds a generator that writes span metrics and service-graph series, under Tempo's names, into the engine's own time-series store, where PromQL, dashboards and alerts read them like any other metric. orbit-api forwards the five APM reads to the engine for a session holding apm.read. No part of this leaves the engine's volume, and no second store or query service is involved. The whole path, and what to send, is apm.md.

What leaves your account: nothing

SRE Orbit is self-hosted. There is no SRE Orbit, Inc. backend these four containers call home to, no telemetry endpoint baked into any image, and no license-check network call. Concretely:

  • From the browser's perspective, web makes no outbound calls: every API call the UI makes is same-origin, to web itself, which then proxies server-side.
  • orbit-stack calls nothing. It listens for remote-write and answers queries; its blocks stay on the volume you gave it.
  • orbit-api calls nocturne and orbit-stack (in-cluster) and, when ORBIT_DEMO_DATA=false, the Kubernetes API your ORBIT_KUBECONFIG points at. It calls nothing on the public internet, with one opt-in exception: set ORBIT_CONTACT_WEBHOOK_URL and it POSTs each lead the site's contact form stores to the URL you named.
  • nocturne calls a model provider only when NOCTURNE_PROVIDER is openai or anthropic, and only after you've also set allowInternetEgress: true for it. These are two separate switches, and neither flips the other. With the default NOCTURNE_PROVIDER=mock, nocturne makes zero outbound network calls; the demo runs with no credential and no egress. What it sends is the conversation and what its tools read: cluster state, and, from a database connection an admin opened to Nocturne, query answers orbit-api masked first (databases.md, "Nocturne on a database").
  • Nothing in this repository sends usage analytics, crash reports, or version-check pings anywhere. If that ever changes, it will be a CONTRACT.md-documented, off-by-default environment variable, and not a silent default.

The data path for a metric, ingest to pixel

Two distinct paths exist today. Conflating them is the most common misunderstanding about this product, so say which one you mean.

Demo mode (NEXT_PUBLIC_DEMO_MODE=true, the default). The Orbit Deck reads directly from apps/web/src/lib/demo-estate.ts, a deterministic, in-process data set shaped exactly like the orbit-api responses in CONTRACT.md (same field names, same QueryResult series shape). There is no network hop: a Server Component calls a function, gets an object back, and renders it. This is why the marketing hero and the Deck show identical numbers; CLAIMS.md calls this "ONE estate, used by the marketing hero and the Deck alike." Time is frozen to a fixed clock so server and client render the same pixels with no hydration mismatch.

Live mode (NEXT_PUBLIC_DEMO_MODE=false, ORBIT_DEMO_DATA=false). A browser request for a Deck page hits web; web's server calls orbit-api over the internal /api/* proxy with ORBIT_AUTH_TOKEN attached; orbit-api resolves the request against the live source (services/rust/orbit-api/src/live.rs) instead of the demo one and returns JSON in the same shape (Cluster[], QueryResult, etc.; see api.md); web renders it with the same components (TimeChart, StatTile) that render the demo estate.

What live mode reads, and what it derives

Credentials come from ORBIT_KUBECONFIG (one cluster per context, the {id} being the context name lowercased with everything outside [a-z0-9-] replaced by -) or, when that is empty, from the pod's own ServiceAccount (ORBIT_CLUSTER_ID names that single cluster). The chart binds a read-only ClusterRole for the in-cluster path under components.orbit-api.rbac.enabled; deploy/kubectl/15-rbac-orbit-api.yaml is the same thing without templating. get, list and watch only, and never on secrets.

Read from the API server: nodes, pods, namespaces, events, PersistentVolumes, and Deployments, StatefulSets, DaemonSets and CronJobs (plus the ReplicaSets and Jobs needed to walk a pod back to the controller that owns it). Node capacity is allocatable, not raw capacity, so a node row and the CPU-saturation panel are measured against the same denominator. Utilisation comes from metrics.k8s.io when the API group is installed (k3s ships metrics-server); when it is not, usage is 0, never an estimate, because a request echoed back as a measurement is worse than a blank.

Derived, because Kubernetes has nothing to read it from:

  • Cluster status. critical when the control plane does not answer or the majority of nodes are NotReady; degraded when any node is NotReady, any workload has been below desired for more than 5 minutes, or any pod is in CrashLoopBackOff; healthy otherwise.
  • Alerts. There is no Alertmanager in this build, so six rules run over the same objects and emit the same Alert shape: NodeNotReady and PodCrashLooping (critical), PodPending past 5 minutes and DeploymentReplicasUnavailable (warning), KubeletVersionSkew and ContainerWithoutLimits (info). Every derived alert is state: "firing" and carries no team: a derived rule has no routing label, and inventing one pages the wrong people. A rule itself always says ack: "open"; someone holding workloads.write can acknowledge an alert or silence it for a set time, which orbit-api keeps in its own store and lays over every read, with who did it and until when. Each rule, and what to check when it fires, is in alerts.md.
  • Cost. monthlyCost is the sum over nodes of an hourly price times 730 hours. Where Karpenter runs (ORBIT_KARPENTER_NAMESPACE, default karpenter), a node is priced from Karpenter's own AWS estimates for its instance type, capacity type (on-demand or spot) and zone, read from the leader's metrics port every 10 minutes. Elsewhere it is priced from an embedded us-east-1 on-demand list of 1,371 EC2 types, a spot node at 30% of it, the median spot share on the day the list was taken. A type in neither is priced at ORBIT_NODE_HOURLY_USD (default 0). Spend is apportioned to namespaces by CPU request. Spot coverage is the share of nodes on spot, read from the capacityType labels the same way the Deck's spot chart counts them. Waste is requests minus usage. Every FinOps payload carries a "source", which the page shows: karpenter when every node was priced from Karpenter, else list-price, else flat. This is an estimate and it is wrong in named ways: it ignores Savings Plans, Reserved Instances, EDP discounts, storage, network and the control-plane fee. Without Karpenter it also ignores the live spot market and every region that is not us-east-1. There is no previous month to compare against, so deltaPct is 0 and forecast is today's shape run for a month, not a projection. Cost Explorer replaces all of this; until it lands, do not put these numbers in front of finance.
  • Recommendations. Rightsizing fires when a workload with two or more replicas burns under half its CPU request, with confidence low because usage here is one sample from metrics.k8s.io, not a p95 over a window. Spot candidacy is medium (interruption tolerance is inferred from the workload kind). Orphan PersistentVolumes are high, because Released and Available are facts the API server states outright.

Telemetry (GET /api/v1/query_range) is not stored by orbit-api at all. With ORBIT_STACK_URL set, each MetricKey the Deck asks for becomes PromQL over kube-state-metrics, node-exporter, cAdvisor or the engine's own TSDB metrics, and the Deck's ad-hoc panel sends raw PromQL through verbatim; the engine's errorType decides whether a failure is the caller's (invalid_request) or the engine's (upstream_error). A metric the estate does not emit comes back as an empty matrix, which reads as "no data" instead of a fabricated line. With ORBIT_STACK_URL empty, query_range answers an empty series carrying the right unit, an ad-hoc expression is refused, and /readyz does not check an engine that is not configured.

Either way, the pixel-rendering half of the path is identical: JSON in a fixed shape in, TimeChart / StatTile / BarRows out, with locale-aware number formatting (CLAIMS.md → "Number formatting by locale") applied at render time so a pt-BR page never prints an en-US numeral.

Where to go next