Gateway inputs¶
These are the variables the brama serve process itself reads.
In a managed installation the launcher assembles the security-bearing ones
before exec; see
Launcher inputs. A missing,
malformed, duplicate, or contradictory value ends startup with a refusal that
names the variable. The route registry file has its own page:
Route registry.
Listener¶
| Variable | Default | Meaning |
|---|---|---|
--port (serve flag) | 8080 | listen port |
BRAMA_BIND_ADDRESS | loopback | bind IP; must parse as an IP address. Requests from this address count as local for the transport guard |
BRAMA_TRUSTED_PROXY_IPS | unset | comma-separated TLS-terminator peer IPs whose https forwarded headers are trusted; an empty value trusts none of them. An entry that is not an IP address is not skipped: every non-loopback request is then refused with 500 internal_error naming the variable and the entry |
BRAMA_ENCRYPTED_PEER_IPS | unset | comma-separated peer IPs whose hop is already encrypted (mesh nodes); accepted without forwarded headers. A malformed entry is refused the same way |
Identity and policy¶
| Variable | Default | Meaning |
|---|---|---|
BRAMA_MODEL_ROUTER_CLIENT_IDENTITIES | unset | JSON array of {client_id, token, agent_id?, allowed_models?}. Absent means "ask the authority", not "misconfigured": a bearer that is not in this table is resolved against Skarbiec, and Skarbiec's answer is the answer |
BRAMA_MODEL_ALIASES | required in managed mode | JSON object of alias → canonical route. Must contain wisent-backend, wisent-backend/evaluation, wisent-backend/embeddings, wisent-backend/moderation, weles, and best; extra names are permitted without widening the required clients' allowlists. In standalone mode an absent value is an empty map |
BRAMA_INFERENCE_ROUTES_FILE | required by the managed launcher; unset in standalone mode | owner-only route registry document, re-read per request; an absent managed path refuses startup, while standalone requests without a registry cannot use dynamic routes. Symlinks and group- or other-readable files are rejected. See Route registry |
BRAMA_REQUEST_SIGN_IDENTITIES | unset | central request-sign identity map (Echo, legacy Content Platform, Oko, Weles) |
BRAMA_REQUEST_SIGN_CAPABILITY_IDS | unset | optional request-sign capability seeds; the managed launcher clears them and issues at final use |
BRAMA_PROVIDER_CAPABILITY_IDS | unset | optional direct-provider capability seeds; the managed launcher clears them and issues at final use |
BRAMA_SUBSCRIPTION_CATALOG | unset | trusted startup subscription metadata the operator declares, read to seed the inventory before live discovery has answered; a discovery refusal is still reported as a refusal |
WC_SKARBIEC_URL, BRAMA_SKARBIEC_CONSUMER, BRAMA_SKARBIEC_TOKEN_FILE | unset | bearer introspection against Skarbiec for tokens not in the boot table |
BRAMA_WISENT_AUTH_URL, BRAMA_WISENT_AUTH_ANON_KEY | unset (Stado's catalog sets both) | the Wisent Identity origin and its public anon key, for human identity and organization authorization; never a service-role key. Nothing is compiled in: with both unset no person can be resolved, with only one set the refusal names the declaration incomplete and which half is missing, and a value that is not Unicode is refused by name |
ENTITLEMENTS_ROUTER_BIN, SKARBIEC_BIN | executable discovery when neither is declared | binary shelled for vault listing and credential writes, in that declaration order; an explicitly empty or non-Unicode value refuses rather than selecting another executable. See selection and diagnostic contract. |
Alias policy and the route registry are separate inputs with separate
jobs. BRAMA_MODEL_ALIASES declares which aliases this
installation is required to serve; the registry says which single destination
each alias resolves to. A declared alias with no destination is a real state,
no_route, and a completion naming it answers 503
alias_unserviceable with details.state and
details.route rather than being routed somewhere else. See
Alias and Errors.
State and ledgers¶
| Variable | Default | Meaning |
|---|---|---|
BRAMA_STATE_DIR | $HOME/.brama | holds journal.jsonl, the append-only retirement/quality/refresh journal; readers take the last matching record; credential material is never written here. With neither this variable nor a home (HOME, else the user database's home for the running account), every command and route that reads or writes Brama's state is refused with neither HOME nor the user database names a home directory, so Brama cannot find its state or the Stado binary; declare BRAMA_STATE_DIR or HOME in the unit's environment. The process keeps running. |
BRAMA_SUBSCRIPTION_USAGE_FILE | ~/.config/brama/subscription-usage.json | per-subscription usage ledger, owner-readable, atomic writes |
BRAMA_DONATED_SUBSCRIPTIONS_FILE | ~/.stado/var/brama/donated-subscriptions.json | metadata-only donation overlay, atomic 0600 rewrite |
BRAMA_PERF_PATH | $BRAMA_STATE_DIR/perf.json (~/.brama/perf.json) | replaceable process telemetry; when neither this nor a state directory can be placed, perf_stats_unplaced is logged once with the cause and the stats are kept in memory only |
Sign-in pacing and freshness¶
Plan readings stay current until the window they describe resets, and a credential is refreshed once its stated expiry has passed; neither has a configurable window.
| Variable | Default | Meaning |
|---|---|---|
BRAMA_CREDENTIAL_SIGN_IN_COOLDOWN_SECS | unset: no cooldown; a failed sign-in is not repeated until the account or Weles revision changes, and the host's brama maintain schedule paces the rest | whole seconds the gateway waits before driving a second sign-in for the same stored credential; a value that is not a whole number stops new sign-ins and the log says BRAMA_CREDENTIAL_SIGN_IN_COOLDOWN_SECS must be a whole number of seconds; it is "<value>" |
BRAMA_SUBSCRIPTION_LISTING_AGE_SECONDS | unset: every caller reads the vault's pool listing, except a caller queued behind a listing already in flight, which takes that listing when it lands | whole seconds a successful pool listing is served before the vault is read again. Whatever the age, one listing runs at a time and the callers waiting on it share its answer, so a burst of requests costs one vault read |
BRAMA_MODEL_DISCOVERY_AGE_SECONDS | unset: every catalog call discovers a credential's models, except a caller queued behind a discovery already in flight for that credential, which takes its answer when it lands | whole seconds a credential's discovered models are served before discovery runs again. Whatever the age, one discovery runs per credential at a time and the callers waiting on it share its answer. A member the ledger already refuses — a grant awaiting a sign-in, a retired member, a recorded block — is never discovered: the request path refuses it from the ledger before any vault child or provider is asked |
BRAMA_MODEL_DISCOVERY_FAILURE_AGE_SECONDS | unset: a refused discovery is tried again on the next call, except by a caller that was waiting while it was refused, which takes that refusal | whole seconds a discovery refusal is answered from memory, with its class, instead of asking the provider again |
BRAMA_VAULT_CHILD_RESIDENT_CEILING_BYTES, BRAMA_VAULT_CHILD_FOOTPRINT_CHECK_SECONDS | unset: a vault child runs until it ends | resident bytes past which a vault command is ended, and how often its footprint is read; a ceiling that is not Unicode or not a whole number, or declared without the cadence, refuses the command by naming the variable. The log names every vault child's operation and pid when it starts and when it ends. |
BRAMA_CAPABILITY_LIFETIME_SECONDS | managed launcher: validated services.brama.capability_lifetime_seconds from the control document; direct gateway: required, with no default | whole seconds a capability issued for one request may wait for its redemption. Missing, zero or malformed policy refuses the managed launch; an unset direct gateway variable refuses issuance naming it. Each request's capability carries one use; Skarbiec drops it once spent. |
No schedule is declared for maintenance: usage reports, token refreshes,
sign-ins and the readiness reading are each taken by a maintenance pass the
serving process runs itself, at start, at each moment its ledger states
something becomes due, and after a refusal for want of a signed-in subscription;
brama maintain asks for one more. Usage reports and token refreshes are free, and
the only quota-spending check is the
explicit admin probe route. Signing an account in is not configurable and not
an operator action: when a provider refuses a grant, or the stored document is
not a credential at all, the gateway asks Weles to sign that account in.
Weles drives the browser on its own host; nothing opens one here.
BRAMA_CREDENTIAL_SIGN_IN_COOLDOWN_SECS sets how often that may
happen for one credential and does not turn it off. A sign-in runs until Weles
reports how it ended.
These ages govern how fresh a reading is, not how long a request may run: a completion and a sign-in each run until the provider or Weles answers, and a failure is reported with the error it ended on. A value that is not a whole number is reported by its variable's name; a stored reading is never served under an age nobody declared.
Catalog and providers¶
| Variable | Default | Meaning |
|---|---|---|
BRAMA_MODEL_CATALOG_URL | https://models.dev/api.json | public metadata origin |
BRAMA_MODEL_CATALOG_TTL_SECONDS | unset: the catalog is fetched once per process | age in whole seconds at which the in-memory catalog is fetched again; any other value stops catalog reads with BRAMA_MODEL_CATALOG_TTL_SECONDS must be a whole number of seconds; it is "<value>" |
BRAMA_MODEL_CATALOG_PATH | unset | read the catalog from a local file instead of the origin |
BRAMA_MODEL_CATALOG_CACHE | $BRAMA_STATE_DIR/models-dev-cache.json ($HOME/.brama when the state directory is unset) | replaceable on-disk cache, kept in Brama's own state directory, never /tmp |
BRAMA_PROVIDER_<PROVIDER>_BASE_URL | built-in | per-provider base override; an exact trusted HTTPS host or an explicit loopback address only |
STADO_INTEGRATION_API_URL, BRAMA_STADO_INTEGRATION_TOKEN | unset | optional remote Stado transport for brama onboard, declared together: an HTTPS origin with no path, query or credentials, and a non-empty token. With neither, each remote journey step is refused as no Stado onboarding route is configured and the journey runs locally; one without the other, a refused origin or token, or a value that is not Unicode is the refusal each step answers with (<step>: STADO_INTEGRATION_API_URL is declared without BRAMA_STADO_INTEGRATION_TOKEN, …, … the declared Stado onboarding connection is refused: …), never reported as unconfigured. A bundle Stado sends is held to the onboarding client's own envelope rules and this product's journey version and first-success fact. |
The catalog describes models; it does not decide routing. An alias is served only through its registered destination, and a model present in the catalog but absent from the registry has no route.
Build identity is baked at compile time from
BRAMA_SOURCE_REVISION, BRAMA_BUILD_PLATFORM, and
BRAMA_BUILD_TIMESTAMP, and reported by
brama version, /health, /readyz, and
/stats.