Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0065

ADR-0065: The production gateway's WS control plane binds loopback through the committed prod profile

field	value
Status	Accepted — Accepted (ruling R15, Mohamed, 2026-09-24: "1, proceed with that")
Date	2026-09-24
Register	factory (`docs/adr`, 4-digit ids)
Source	`docs/adr/0065-prod-gateway-binds-loopback-through-the-committed-profile.md` — permalink at `0fe7f2e36` (unchanged on master since that commit)
Wiki register entry	ADR-0065 (wiki status: Accepted)

← ADR-0064 · ADR-0066 →

The record

Status: Accepted (ruling R15, Mohamed, 2026-09-24: "1, proceed with that") · Date: 2026-09-24

Context

orchestrata-gateway.service under /opt/orchestrata binds its WebSocket control plane to GATEWAY_HOST (gateway/config.py). Wave-7 ship attempt 5 (2026-09-24, unit orch-ship17) reached the promote's services stage and the gateway failed to start: the only GATEWAY_HOST it could see was the workspace .env template's CHANGEME placeholder, because deploy/install-orchestrata.sh had defaulted --secrets-env to $SOURCE_REPO/.env and the committed env/prod.env deliberately does not set the key (its comment reads "The WS control plane keeps binding GATEWAY_HOST (127.0.0.1 in prod) and is NOT exposed by this key" while exposing only GATEWAY_HTTP_HOST=10.53.1.1). env/test.env already pins GATEWAY_HOST=127.0.0.1 explicitly, with the reasoning that the in-process gateway tests must keep binding localhost. Nothing on the host needs the prod WS control plane on a routable address: every client of it (the CLI, hooks, the kernel) runs on this host.

Decision (Mohamed, ruling R15)

env/prod.env sets GATEWAY_HOST=127.0.0.1 explicitly, mirroring env/test.env. The WS control plane of the production gateway binds loopback only; the HTTP observability surface keeps its own key (GATEWAY_HTTP_HOST) and its own bind address. A test pins the prod profile's value so a later edit cannot silently reopen the bind.

Alternatives rejected

Put GATEWAY_HOST in the secrets file: it is not a secret, and the contract for the secrets file (ADR-0066) is secrets only. A config value hidden in a 0600 file is invisible to review.
Bind the control plane on 10.53.1.1 like the HTTP surface: nothing on the fleet speaks the JSON-RPC control plane, and exposing it widens the attack surface for no client.
Give the gateway a code default of 127.0.0.1: the placeholder discipline (ADR-0066, U-BOOT3's refusal of CHANGEME) exists precisely so that unset keys fail loudly instead of falling back.

Consequences

The prod promote's services stage can start the gateway from the committed profile alone. env/prod.env and env/test.env agree on the key. The next ship carries the profile change (U-PROD2) and the re-bootstrap of /opt/orchestrata picks it up through advance_tree.

Provenance

Orchestrator finding on 2026-09-24 (plan plans/PLAN-2026-09-23-production-deployable-tools.md, records "ship attempt 5" and R15). Mohamed's ruling, 2026-09-24: "1, proceed with that" (accepting the recorded recommendation 127.0.0.1) and, the same turn, "record tbe adr decisions". Evidence: scratchpad/ship-wave7e.log (services stage failure), env/test.env:61-70, env/prod.env:53-56.

Also mentioned: ADR-0066

Rulings cited

None.

Specs cited

None (or no spec page exists for the ones named).