Configuration¶

This page is the index of Brama's configuration surface. It says which configuration Brama generates for itself, which configuration belongs to the operator, and where each variable, file, and validation rule is documented. The three subpages below hold the detail: the variables the gateway process reads, the route registry document on disk, and the inputs the managed launcher requires before it starts the gateway.

Generated versus operator-owned¶

Production configuration is generated, not hand-authored. src/release/bin/start-with-skarbiec assembles the security-bearing variables from operator-owned policy and scoped Skarbiec consumers, then execs brama serve. Missing, malformed, duplicate, or contradictory security configuration ends startup with the exact refusal naming the offending input; no credential, provider, identity, or storage input is substituted for another, and nothing is invented for the operator.

Three things are operator-owned and are the only configuration an operator edits directly:

• the non-secret service policy document BRAMA_CONTROL_CONFIG, which declares allowed models, model aliases, required provider capabilities, and the request capability lifetime in whole seconds;
• the service environment file BRAMA_SERVICE_ENV_FILE (default ~/.config/brama/service.env), which carries paths and feature switches but never capability IDs or provider credentials;
• the route registry document at the required BRAMA_INFERENCE_ROUTES_FILE path, which is also written by Brama's own admin route and CLI.

Everything else — capability IDs, request-sign identities, provider credentials, the derived client grant — is issued at final use from vault bindings and is not something to write into a file by hand.

The route contract in one paragraph¶

An alias resolves to exactly one route. The registry maps an alias to a single destination, and when that destination refuses, the refusal is what the caller receives. No second route is attempted, and Brama adds no elapsed-time cutoff. The four alias states are serving, no_route, capability_absent, and routes_file_invalid; they are reported by GET /v1/aliases and by brama aliases. The document shape that carries this, its validation guards, and the migration command that moves an existing file to it are on Route registry.

The derived client grant¶

The managed launcher derives the wisent-backend client's exact four-alias grant from the required policy: wisent-backend, wisent-backend/evaluation, wisent-backend/embeddings, and wisent-backend/moderation. Extra operator aliases remain in the route registry but are not automatically granted to this client. Startup checks that every required alias is in the client's grant and accepts a grant that holds more; when one is missing the refusal is BRAMA_MODEL_ROUTER_CLIENT_IDENTITIES must give `wisent-backend` every required alias, followed by required= and observed= lists.

Pages in this section¶

Applying a change¶

Restart after any startup policy change. The gateway re-reads the route registry per request, so route edits take effect without a restart, but it does not re-read client identities, the alias policy, or capability maps in place. Runbook covers the operational sequence and Errors the refusal codes a bad input produces.