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
| Component | Language | Image | Container port(s) | Purpose |
|---|---|---|---|---|
web | TypeScript, Next.js 16 (standalone) | ghcr.io/sreorbit/web:0.1.0 | 3000 | Marketing site + Orbit Deck UI. The only component an ingress ever routes to. |
orbit-api | Rust | ghcr.io/sreorbit/orbit-api:0.1.0 | 8080 (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. |
nocturne | Rust | ghcr.io/sreorbit/nocturne:0.1.0 | 8081 (API), 9090 (metrics) | AI assistant. Provider-abstract, streams over SSE. Never reachable from outside the cluster network. |
orbit-stack | Rust | ghcr.io/sreorbit/orbit-stack:0.1.0 | 8082 (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
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:
- The browser never talks to
orbit-apiornocturnedirectly.webis the only component withingress.enabled: truein the Helm chart, the only one with a path indeploy/kubectl/60-ingress.yaml, and the only one docker-compose exposes for anything other than local debugging.NEXT_PUBLIC_API_URLdoes 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/*toorbit-apiand attachesORBIT_AUTH_TOKENitself; the token never reaches client JavaScript. nocturnehas no public surface at all. It has no ingress rule, no CORS configuration, and (in Kubernetes) a NetworkPolicy that admits traffic fromorbit-apionly.orbit-apiexposesPOST /api/v1/nocturne/chat,POST /api/v1/nocturne/analyzeandGET /api/v1/nocturne/modelsas a streaming reverse proxy tonocturne, attachingNOCTURNE_AUTH_TOKENon that internal hop. An LLM endpoint reachable from the internet lets anyone who finds the URL run up your model bill; seesecurity.md./metricsis 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; seesecurity.mdandoperations.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 ofAuthorization: Bearer <token>againstORBIT_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, checkingexp/iss/aud, with a bounded key-refresh cache.disabled: local demos only. The service logs aWARNnaming the risk on every startup, and refuses to start ifORBIT_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 fromorbit-apiand keeps it in theHttpOnlycookieorbit_session. Page JavaScript never sees it. - On every proxied call and every server-side read,
webcopies that value intoX-Orbit-Sessionbeside the bearer, and never forwards the browser'sCookieheader. orbit-apichecks 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 andcontact.- When someone asks Nocturne a question, their session rides along to
nocturneand 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,
webmakes no outbound calls: every API call the UI makes is same-origin, towebitself, which then proxies server-side. orbit-stackcalls nothing. It listens for remote-write and answers queries; its blocks stay on the volume you gave it.orbit-apicallsnocturneandorbit-stack(in-cluster) and, whenORBIT_DEMO_DATA=false, the Kubernetes API yourORBIT_KUBECONFIGpoints at. It calls nothing on the public internet, with one opt-in exception: setORBIT_CONTACT_WEBHOOK_URLand it POSTs each lead the site's contact form stores to the URL you named.nocturnecalls a model provider only whenNOCTURNE_PROVIDERisopenaioranthropic, and only after you've also setallowInternetEgress: truefor it. These are two separate switches, and neither flips the other. With the defaultNOCTURNE_PROVIDER=mock,nocturnemakes 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 answersorbit-apimasked 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.
criticalwhen the control plane does not answer or the majority of nodes areNotReady;degradedwhen any node isNotReady, any workload has been below desired for more than 5 minutes, or any pod is inCrashLoopBackOff;healthyotherwise. - Alerts. There is no Alertmanager in this build, so six rules run over the same
objects and emit the same
Alertshape:NodeNotReadyandPodCrashLooping(critical),PodPendingpast 5 minutes andDeploymentReplicasUnavailable(warning),KubeletVersionSkewandContainerWithoutLimits(info). Every derived alert isstate: "firing"and carries noteam: a derived rule has no routing label, and inventing one pages the wrong people. A rule itself always saysack: "open"; someone holdingworkloads.writecan acknowledge an alert or silence it for a set time, whichorbit-apikeeps 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 inalerts.md. - Cost.
monthlyCostis the sum over nodes of an hourly price times 730 hours. Where Karpenter runs (ORBIT_KARPENTER_NAMESPACE, defaultkarpenter), 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 atORBIT_NODE_HOURLY_USD(default0). Spend is apportioned to namespaces by CPU request. Spot coverage is the share of nodes on spot, read from thecapacityTypelabels 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:karpenterwhen every node was priced from Karpenter, elselist-price, elseflat. 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 notus-east-1. There is no previous month to compare against, sodeltaPctis0andforecastis 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
lowbecause usage here is one sample frommetrics.k8s.io, not a p95 over a window. Spot candidacy ismedium(interruption tolerance is inferred from the workload kind). Orphan PersistentVolumes arehigh, becauseReleasedandAvailableare 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
- Installing: pick a path in
install/README.md. - Every variable named above, in one table:
configuration.md. - The threat model this boundary is designed against:
security.md. - Every route, shape and limit sketched here in full:
api.md. - Users, roles and sessions:
identity.md; traces and APM:apm.md.