Launcher inputs¶

src/release/bin/start-with-skarbiec is the managed entry point. It reads operator-owned policy, provisions or verifies this installation's trust material, derives the security-bearing variables the gateway reads, and then execs brama serve. This page lists what the launcher itself requires. What it hands to the gateway is on Gateway inputs.

Required inputs¶

The launcher reads BRAMA_SERVICE_ENV_FILE (default ~/.config/brama/service.env) first, then requires:

• BRAMA_GNUPG_HOME — the service's GnuPG home. Startup ends without it; no other home is used in its place.
• SKARBIEC_VAULT_FILE — the authorized encrypted vault.
• BRAMA_CONTROL_CONFIG — the authoritative non-secret service policy document. The launcher reads services.brama.{allowed_models,model_aliases,required_provider_capabilities,capability_lifetime_seconds} and rejects policy that is absent, malformed, or inconsistent with itself. capability_lifetime_seconds is a positive whole number the operator declares for the lifetime of one request-path vault capability; the launcher chooses no value for it.
• BRAMA_INFERENCE_ROUTES_FILE — the owner-only route registry path declared for this installation. Startup refuses it when absent rather than placing routes under an assumed home.
• BRAMA_DONATION_RECIPIENT_KEYS (default ~/.config/brama/recipient-public-keys.asc) — the armored public keys this installation encrypts donated subscriptions to. The release ships none: the recipients are the installation's choice. Each new installation directory is seeded from this file, and one that already holds its keys keeps them. With neither, startup ends with no donation recipient keys: <installation file> is absent and <declared file> is not a file; put the armored public keys donated subscriptions are encrypted to there, or name the file with BRAMA_DONATION_RECIPIENT_KEYS.

The managed entry point invokes brama launcher policy --config <control> --allowed <new-file> --aliases <new-file> --backend <new-file> --lifetime <new-file>. It validates the whole document before writing owner-only outputs. A missing or invalid lifetime names services.brama.capability_lifetime_seconds in the CLI refusal and prevents the gateway from starting.

An input that is missing, malformed, duplicated, or contradicted by another input ends startup with a message naming it. The launcher does not proceed on a partial policy and does not choose a value the operator did not declare.

What it derives and provisions¶

From these declarations the launcher derives the identity and policy variables the gateway reads, including the wisent-backend client's exact four-alias grant, and it provisions or verifies this installation's trust material.

The launcher also seeds the route registry file when it is absent, creating it owner-only from the validated alias table rather than guessing routes. Its path and shape are on Route registry; an existing file written against an older shape is moved to the current one by brama routes migrate, which keeps only the known top-level fields, validates the result, commits it with the same atomic owner-only replacement, and prints it.

Shared capability broker¶

The Skarbiec service must already expose its capability listener through skarbiec serve --socket <path> or its service's SKARBIEC_CAP_SOCKET. The launcher runs skarbiec capability status --socket <path> before handing over to Brama. That command exchanges a real request with the listener and checks that the vault, capability state and route table match this client's absolute paths. A missing listener, an unsupported broker, or different state paths stops startup with the failed operation and observed paths.

listening proves that exchange, not credential decryption or provider availability. Grants, workload proofs and one-use limits are still enforced at redemption. Brama does not kill a socket owner, delete the shared socket, or start a private broker when inspection fails.

Before a release ships, brama launcher verbs --router <pinned router> --launcher <entry point> checks that the pinned router implements every command the launcher sends it. It reads the entry point and every .sh stage under the launcher/ directory beside it with the POSIX shell grammar: a call is a simple command whose command word is "$ENTITLEMENTS_ROUTER_BIN" as written, including after exec, an environment prefix, !, a pipe, a list operator, a compound command, a case item or inside a command substitution. The same literal as an operand, test operand, assignment, redirection target, case pattern, loop word, comment, here-document or quoted string is no call. It prints launcher requires: …, then either confirms the router advertises every path or refuses with the pinned broker does not implement: …. A stage the grammar cannot read refuses with its path and the construct it ends inside; a launcher that is not UTF-8 text, or a path with no directory, refuses by name.

Capability material is issued, not configured¶

Runtime capability IDs are freshly issued from vault bindings at final use. The launcher clears any capability seeds it finds in the environment before it execs the gateway. Never write capability IDs or provider credentials into the non-secret env file: they belong to the vault and to the capability socket, and a value placed in the env file is cleared rather than honoured.

deploy/*.env.example documents the operator-facing subset of these inputs. Security explains the trust boundary the capability socket enforces.

Applying a change¶

Restart after any startup policy change. The gateway re-reads the route registry per request, but it does not re-read client identities, the alias policy, or capability maps in place, so a change to those takes effect at the next start. Runbook has the restart sequence and the checks to run afterwards.