Provider¶

A protocol adapter with a trusted endpoint. The provider table says what the gateway can speak; whether it may spend through a provider is a separate question answered by a capability or a subscription. A catalog entry never unlocks a credential or manufactures availability.

The descriptor table¶

src/providers/adapter.rs declares 24 provider descriptors. Each carries an id, display name, base URL, models path, chat path, decision path, wire protocol, and auth kind; /stats and /v1/admin/snapshot report every descriptor with a configured flag, the endpoint it resolves, and whether it serves chat or decisions.

No route stands for a model Brama chose: embeddings and moderation name a concrete OpenAI model (openai/text-embedding-3-small, openai/omni-moderation-latest) like chat does. There is no per-provider default model: a caller that wants "the model this gateway chooses" names an alias (best, or one the route registry declares with brama aliases set), and the registry says where it points.

local-openai is the deployment-owned inference target: its base URL resolves per request through the routes file, and only loopback or Tailscale IPv4 endpoints are accepted (alias). Brama does not start or supervise a local inference engine — the deployment owner controls the digest-pinned vLLM lifecycle.

Endpoint trust and overrides¶

Provider clients require approved HTTPS hosts, disable redirects, and bypass ambient proxies. BRAMA_PROVIDER_<PROVIDER>_BASE_URL (the provider id uppercased, non-alphanumerics to _) overrides one provider's base, and the override is validated with these exact refusals (src/providers/adapter/registry/address.rs):

• providerbase URL must not contain surrounding whitespace
• providerhas an invalid base URL: <error>
• providerbase URL must be an absolute URL without user info
• providerbase URL must not contain a query or fragment
• providerbase URL has no host
• provideris declared with, which names no host
• providerbase URL must use HTTPS (non-loopback hosts)
• providerhostis not trusted: it is declared at (the trusted host is the host of the address the provider is declared with: its roster entry, or for a public-catalogue provider the endpoint Brama keeps for its models.dev id; an override may change the path, not the host)
• providerloopback endpoint requires an explicit deployment override (loopback is accepted only through the env override, http or https)

The same validated, override-aware base serves both the chat route and the plan-usage route, so a provider pointed at a proxy does not keep one of its two endpoints pointed at the open internet.

Plan-usage publishers¶

Brama supports three free plan-usage endpoints with the subscription credential already used for inference. Other providers are explicitly reported as unsupported by this path; that is not a claim that the vendor has no separately privileged organization or billing API. Observed traffic counters remain available (subscription):

Bounds¶

Per attempt: no clock ends a provider call; it runs until the provider answers or refuses, and its answer is read whole before UTF-8 or JSON parsing (a body that is not UTF-8 is provider_failure: provider response is not UTF-8). Public model metadata comes from models.dev (BRAMA_MODEL_CATALOG_URL, default https://models.dev/api.json, kept in memory for BRAMA_MODEL_CATALOG_TTL_SECONDS or for the life of the process) and is advisory only.

Not to be confused with¶

• A capability. The descriptor is speech; the capability is spend.
• A subscription provider. claude-code, codex, and kimi are normal descriptors whose credentials happen to be OAuth grants in the shared subscription pool rather than the deployment's own keys.