`brama workload register`¶

Register this installation's workload key with the vault that guards it. The broker redeems a capability only for an agent the vault holds a live grant for, carrying that workload's public key; this command issues that grant from what the installation already holds.

Invocation¶

brama workload register [--json]

What it reads and writes¶

The entitlements router and vault come from ENTITLEMENTS_ROUTER_BIN and SKARBIEC_VAULT_FILE (environment, then the running installation under ~/.stado/services/brama/current, then service env). The public key and agents come from the first workload in <config dir>/registry.json; the capabilities are every acquire:<item>#<field> that capability-routes.json maps. For each agent it runs skarbiec-entitlements-router grant issue --replace-capabilities, so the grant holds exactly those capabilities and nothing more. The private key never leaves the installation and no secret is printed. The launcher runs this on every start; a rerun replaces the same grant.

Lifetime¶

Skarbiec requires an acquire grant to state its lifetime and refuses --until-revoked for one. The lifetime is the operator's: BRAMA_RUNTIME_GRANT_SECONDS in the installation's ~/.config/brama/service.env, a whole number of seconds above zero, passed as --ttl-seconds. Brama chooses none. The launcher registers on every start, so the period has to cover the longest the gateway runs between starts; the grant ends when it passes, and every redemption after that is refused by Skarbiec until the next registration.

Output¶

routes, registry, granting, lifetime_seconds, granted (each agent with workload_bound and expires_at) and refused (each agent with the cause its grant was not issued) as key: value lines, or one document with --json. Every agent is issued in turn whatever the one before answered, so the answer names exactly which agents were re-granted and which were not. Exit 0 means every agent's grant was issued; with any refusal the whole answer is printed, then brama workload register: <n> agent(s) were not re-granted: <agent>: <cause>; … on standard error and exit 1.

Refusals¶

Each exits 1 before any agent is issued:

cannot resolve the running installation <current>: <cause>; <installation> holds no bin directory, at its root or in a platform directory; <installation> holds several platform directories with a bin directory, so which one runs is not stated: <directories>
ENTITLEMENTS_ROUTER_BIN, SKARBIEC_VAULT_FILE and BRAMA_SKARBIEC_CONFIG_DIR must be named by the running installation, environment, or service env
no workload registry at <path>; cannot read workload registry <path>: <error>; workload registry <path> is not JSON: <error>; workload registry <path> declares no workload
<registry> names no proof key or agent to bind it to
no capability routes table found at <paths tried>; <routes> is not JSON; <routes> maps nothing, so there is nothing to grant
<home>/.config/brama/service.env declares no BRAMA_RUNTIME_GRANT_SECONDS: Skarbiec requires the runtime grant to state its lifetime and Brama chooses none, so state the grant period in whole seconds; BRAMA_RUNTIME_GRANT_SECONDS must be a whole number of seconds above zero; it is "<value>": <error>
proof key is not base64: <error>
Per agent, under refused: grant issue could not run: <error>; grant issue refused it: <router's own answer>; grant issue succeeded but answered no JSON: <error>; grant issue did not answer workload_bound=true for the key it was given: <answer>; grant issue answered no expires_at: <answer>; the workload public key file could not be removed after grant issue: <path> is left behind: <error>