brama diagnose¶

On the gateway's own host, explain why Brama is or is not serving. It opens every file the launcher reads, in the order the launcher reads them, and prints each beside what it has to agree with.

Invocation¶

brama diagnose [--json]

What it reads¶

Sections, in order:

• units that start Brama — ~/.stado/services/brama/current, where it points, and the release state ~/.stado/release-state/brama.json records as serving.
• installed generations — every installed generation, the files it is missing, whether its entitlements router answers grant capability, and whether its trust registry pins that exact binary. A generation's files are read from its root when it carries bin/ there, otherwise from the one platform directory inside it that does, whatever that directory is named; a directory with neither, or with several such platform directories, is printed as <path>: not a generation: <reason>. brama workload register reads the running installation's files the same way.
• service env — ~/.config/brama/service.env; a value is shown only when it is an existing path, so no secret is printed.
• policy grants against authority routes — the provider grants in the generation's policy.json against the authority-owned routes table.
• alias routes against routed provider grants — each alias route against the providers policy and routes both allow. In both sections a file is called absent only when it does not exist; one that exists and cannot be read is printed as <path>: cannot be read: <cause>, one that does not parse as <path>: not JSON: <cause>.
• reachability — the loopback port service.env names (or a line saying it names none), the address the gateway announced when it bound, and every origin tailscale serve status publishes, each with the status it answered.
• why the release stopped serving — from Stado's release state (~/.stado/release-state/brama.json): the rollout phase, the active release with its pid and start, or active: none, so no Brama release serves this host; when the active release last answered its readiness read; the agent's detail; and every quarantined candidate digest, newest first, with the instant, the cause the release agent named, the evidence line it read it from and the whole reason. The section ends with the repair: stado release doctor brama --json names each cause's remedy and whether the release agent retires that record by itself; a cause that holds the candidate is cleared after its repair with stado release quarantine clear --digest <digest> --reason <text>. A host with no release state says no release state is recorded on this host, so no release agent has run Brama here.
• current boot attempt — the whole unit log (~/.stado/logs/<unit>.log) from the last line brama launcher: boot attempt of <installation>; a log written by a launcher that predates that line is shown whole under the unit's log (no boot attempt marker in it).

Output and state¶

Read-only: it writes nothing and contacts no provider. A file it cannot read is reported as a line in its section rather than ending the report, so one missing file does not hide the others. It exits 0 once the report is printed; the report, not the exit status, says whether the gateway can serve. To see whether each alias actually answers, run brama probe.

Refusals¶

An unknown argument is refused by the parser with exit 2. There is no other refusal.

Back to the complete CLI command tree.