BBramaDocs

Brama onboarding: paths and prerequisites

Paths and prerequisites

Brama gives Wisent services one authenticated gateway for provider-neutral LLM inference without distributing provider credentials to callers. This page picks the path you are on, lists what that path requires, and states how an installation selects the release it runs.

Choose a path

  • Safe local detection: no credentials, service, state, provider network, or model cost. Every maintainer starts here.
  • Authenticated loopback gateway: real HTTP boundary on one host; requires generated client and Skarbiec capability configuration and may contact a provider only when an inference endpoint is called.
  • Production host service: operator-managed Linux host, immutable GitHub Release, trusted TLS terminator, local service policy, and scoped Skarbiec grants.

Do not begin with production configuration or a provider call. Each path is walked in first success.

Prerequisites

Required for safe local detection:

  • macOS or Linux;
  • Git;
  • Rust/Cargo compatible with Cargo.lock;
  • either the newest published release archive or a source checkout.

Required for an authenticated loopback gateway:

  • all safe-path prerequisites;
  • the packaged or explicitly selected entitlements-router;
  • GnuPG and an authorized local Skarbiec vault;
  • this installation's provisioned trust material and its owner-bound capability socket;
  • generated client identities, aliases, and capability maps;
  • one free loopback port.

Additional production prerequisites:

  • supported Linux architecture and the runtime shared libraries in the release;
  • an operator-owned host service account and service manager;
  • HTTPS ingress whose exact peer IP is in BRAMA_TRUSTED_PROXY_IPS;
  • access to the selected GitHub Release archive and checksum;
  • scoped Skarbiec consumers documented in deploy/*.env.example;
  • operator-owned backup and rollback access to the materialized vault and Brama journal.

Check prerequisites with their own version/help commands. Do not paste tokens or private keys into a shell command merely to check them.

What an alias requires

An alias you intend to serve needs exactly one destination route and the capability that route requires. There is no ordered list of spare routes for an alias: an alias resolves to one route, and when that route refuses, the refusal is what the caller receives. Plan capabilities per alias accordingly, and read the per-alias readiness rows from brama aliases, which prints alias, state and route.

The four alias states are serving, no_route, capability_absent and routes_file_invalid. Only serving means the alias can answer a completion; the other three name the exact repair, described in failures and reset.

Release selection

Immutable Brama releases are published. main is development source and must never be represented as a release. For which release is newest, read released-surface.json or the repository's GitHub Releases list; this page does not restate a version it cannot keep current.

Installation must select:

product version + source revision + platform + archive SHA-256 + provenance

from the GitHub Release described in RELEASE.md, verify the digest, and install the packaged binary and launcher. A source checkout is never the normal production installation model.

A release whose registry document predates the current shape is moved forward with brama routes migrate before the service is started, so the document carries only the known top-level fields the deserializer accepts.

Next