Quick start and interfaces¶

Quick start¶

The normal path is the published release. brama detect is the safe first command either way: it reads local hardware, performs no provider request, reads no credential, creates no Brama state, and incurs no model cost.

Download the release for your platform from https://brama.wisent.com/download, verify the manifest's signature and the archive's digest, and unpack it, as Download shows step by step; then run ./bin/brama detect.

Serving traffic takes more than the archive. Provision this installation's trust material once with bin/provision-skarbiec-trust — the archive ships no signing key and the launcher refuses to start until that material exists — then read ONBOARDING.md before the first authenticated request.

Maintainers working on unreleased source run the same command from a checkout, which needs Git and the Rust toolchain required by Cargo.lock (the production build uses the pinned builder in Dockerfile):

git clone https://github.com/wisent-ai/brama.git brama
cd brama
cargo run --locked -- detect

Expected output contains these fields with host-specific values:

GPU Type: ...
VRAM: ... GB
RAM: ... GB
CPU Cores: ...

Neither command starts a service. The checkout path may leave build output under target/; it is a local build cache, not product state. Continue with ONBOARDING.md for the authenticated loopback and production operator paths. Runnable, risk-labeled workflows are indexed in examples/.

Primary interfaces¶

HTTP inference: POST /v1/chat/completions, /v1/messages, /v1/responses, /v1/embeddings, and /v1/moderations are the canonical model-execution interfaces. The three chat formats share one routing decision, one identity contract, and one attempt budget; they differ only in the shape of the request and the answer.
Streaming: any of the three chat formats streams when the request asks for it -- "stream": true on chat completions and Anthropic Messages, "stream": true on Responses. The response is text/event-stream in the caller's own dialect: chat.completion.chunk frames closed by data: [DONE], Anthropic message_start/content_block_*/message_stop events, or response.* events closed by response.completed. A stream that ends without its terminal event is a generation that was cut after it committed; the caller holds an incomplete answer and Brama has already stopped. Rotation across models and credentials happens only before the first byte, so a committed stream is never silently re-run.
Account API keys and subscriptions: authenticated Wisent users use GET|POST /v1/account/subscriptions and DELETE /v1/account/subscriptions/:subscription_id. Brama derives the owner from the verified Wisent session; the caller never supplies an account or agent identifier. POST accepts an API key for any supported remote provider, stores it through Skarbiec without returning it, and makes that account's canonical provider/model routes available for buffered and streamed calls.
HTTP discovery: GET /v1/models; account discovery combines public catalog metadata with models executable by that account's stored keys, while signed agent discovery includes the shared subscription pool.
Subscription lifecycle: GET, POST, and DELETE /v1/subscriptions/:agent_id; always bearer- and HMAC-protected. A GET returns, per subscription, the plan windows the provider itself reported (limits: used_fraction, window_label, resets_at_ms, and the recorded_at_ms the reading was taken at), what Brama measured (measured: requests, failures, input and output tokens, first and last use), any rate-limit block in force, when the record last changed (observed_at_ms), where the newest window came from and whether it is still current (usage_source: provider, traffic or probe, and stale), the newest proactive check (probe: attempted_at_ms, ok, detail when there is something to explain, and source -- usage_report or completion), and where the credential itself stands (credential: state -- active, needs_reauthorization or disabled -- with cause, recorded_at_ms, expires_at_ms and refreshed_at_ms; null while nothing has been recorded about the grant). credential.state is what separates a subscription that is quiet from one whose sign-in is overdue, and cause is the provider's own sentence for the refusal.
How fresh a plan window is: usage_source names which statement the newest window is -- the provider's own usage report, the headers of real traffic, or an operator's probe -- and is null when there is no window to attribute. stale is true when the newest usage report failed or a served window's own reset instant has passed. Every recorded reading is served, because a number that says when it was taken is information and an empty plan is not; a newer reading replaces it.
What an empty limits array means: one of four states, and the newest check is what tells them apart. Windows present: render them, aged by the newest recorded_at_ms, and say "as of" only when stale is false. Empty with probe.ok false: the credential or the provider refused, and probe.detail is its own sentence. Empty with no probe and nothing measured: nothing has ever gone through this subscription. Empty with probe.ok true: the provider genuinely publishes no plan state, and probe.detail says so when the provider publishes no usage report at all. Only the last of those may be shown as "no plan window", and none of them is a zero.
Operations: public GET /health and GET /readyz; protected GET /stats. /health is liveness only and says so in its body (dependencies: not_probed): it answers ok from a gateway whose every credential redemption is being refused. /readyz is the one that answers whether the product works: it redeems one capability per configured provider and returns 503 naming the providers that failed, with no secret in the body. Deploy checks and uptime monitors should read /readyz; /health only proves the process is running.
Error contract: a refused redemption is 503 authorization_error with code credential_unauthorized and retryable: false, never a 429 capacity_error. Waiting does not repair an authorization id that does not match, and classifying it as capacity sends the caller into retries and the operator into the subscription catalogue.
Desktop control plane: brama-desktop alone may call GET /v1/admin/snapshot, PUT /v1/admin/routes, the GET, POST, and DELETE /v1/admin/subscriptions/:agent_id family, and POST /v1/admin/subscriptions/:agent_id/:subscription_id/probe, which is the only endpoint in the product that deliberately spends plan quota. These endpoints return identifiers, usage and status only; subscription credentials remain write-only.
CLI: serve, version, detect, test, subscriptions list, subscription refresh, collect-task-quality, and mcp. Billable commands require an explicit cost acknowledgement, and commands that mutate state require an explicit --reason.
MCP: read-only stdio JSON-RPC exposing brama_detect only. Model execution, credential discovery, collection, and mutation are deliberately excluded.

The complete state, error, retry, authorization, and resource contract is in CORE.md. Provider capability and lifecycle contracts are in INTEGRATIONS.md.