brama probe¶
On the gateway's own host, send one real completion per alias through the running gateway and report what each one answered. /health answering says the process started; this says whether a model answers through each alias.
Invocation¶
brama probe --bearer-role <ROLE#FIELD> [--agent <AGENT> --signing-role <ROLE#FIELD>] [--alias <ALIAS>]... [--json] --allow-provider-cost| Input | Required/default | Meaning |
|---|---|---|
--bearer-role <ROLE#FIELD> | required | The vault role whose item holds the client bearer every request presents, and its field: the one live item tagged stado:role:<ROLE>, read through the entitlements router ~/.config/brama/service.env names, never printed and never put in an argument. No item is named, so replacing the item changes nothing here. |
--agent <AGENT> | optional; needs --signing-role | Sign every request as this agent with the x-agent-id, x-agent-timestamp and x-agent-signature headers. A subscription selector alias such as best needs a signed request. |
--signing-role <ROLE#FIELD> | optional; needs --agent | The vault role whose item holds that agent's request-sign secret, and its field. |
--alias <ALIAS> | repeatable; every declared alias | Which aliases to request. Without one, every alias the gateway declares — the list brama aliases reports — is requested. |
--json | optional; off | Print the findings once as one JSON document instead of one line per step. |
--allow-provider-cost | required | Acknowledge that each alias spends one short provider request. |
Output and state¶
It tries 127.0.0.1:<PORT> when service.env declares PORT (no port is assumed: the launcher itself refuses to start without one), then the address the last boot announced in the gateway's log, and stops at the first that answers GET /health. Each alias then gets {"model": alias, "messages": [{"role": "user", "content": "say ok"}]} on POST /v1/chat/completions. Lines read health <status> at <address>, then <alias> <status> model=<served> said="…" for an answer, <alias> <status> <refusal body> for a refusal, or <alias> unreachable <error>. With --json: {"addresses": [{address, health | error}], "signing": null | {agent}, "aliases": [{alias, status, model, said | refusal | error}]}.
It writes nothing and changes no configuration. It exits 0 only when every requested alias answered 2xx with nonblank text content. A successful HTTP response without an answer is counted as unserved and includes its response body in the refusal.
Refusals¶
| Sentence | Exit | Meaning |
|---|---|---|
refusing billable probe requests without explicit --allow-provider-cost | 2 | Nothing was read or sent. |
clap's own refusal for a missing --bearer-role, or --agent without --signing-role | 2 | The invocation is incomplete; nothing was read. |
service env names no entitlements router | 1 | ~/.config/brama/service.env has no ENTITLEMENTS_ROUTER_BIN; this is not the gateway's host, or its installation is incomplete. |
cannot read the bearer <ROLE#FIELD> through <router>: <cause> | 1 | No item, or several, carry the role tag, the router refused, or the field is empty; the cause names which. |
cannot read <ROLE#FIELD> to sign as <AGENT>: <cause> | 1 | The request-sign secret could not be read; nothing was sent unsigned in its place. |
`<value>` is not `<role>#<field>` | 1 | The coordinate has no # or an empty side. |
this gateway declares no alias and none was named with --alias; `brama routes set` declares one | 1 | There is nothing to probe. |
no candidate address served /health: service.env names no PORT and the gateway announced no address, or none answered (each tried address is listed above) | 1 | The gateway is not listening on any address it was expected on, or there was no address to try; each attempt's transport error is printed above. |
N of M alias(es) were not served (<alias>, …); each line above names the refusal or the transport error | 1 | At least one alias failed. A 2xx response with missing or blank first-choice text is a refusal; its response body is shown to diagnose what the gateway returned. |