brama routes migrate¶

Rewrite this host's route registry into the document shape the gateway reads today: keep the known top-level fields, validate the result, and commit it with the same atomic owner-only replacement every other registry write uses. Run it once per file; running it again changes nothing.

Invocation¶

brama routes migrate [--file <FILE>] [--json]

Why it exists¶

A registry document carries exactly three known top-level fields — schema_version (the number one), deployments, and routes, which maps each alias to its single destination. An unknown top-level field is refused by name and the whole document is rejected, so a file written against an older shape stops the gateway from serving anything in it and reports the alias state routes_file_invalid.

This command is the repair, and it is the only one: it reads the document as written, retains the known top-level fields, validates what remains exactly as the gateway would, and writes it back through a 0600 staging file and a rename. Nothing is edited by hand, nothing is merged, and no alias is invented — an alias whose destination does not validate keeps the file unchanged and the refusal is reported.

What it reads and writes¶

One file: the registry named by --file, or the default destination. It contacts no provider, redeems no credential, and reads no subscription. The file must be a regular non-symlink file owned by the Brama user and unreadable by group or other, exactly as the gateway requires at request time; a violation of any of those is reported and the file is left as it was.

Output and state¶

The path that was migrated, the size of each collection in the resulting document, and one line per alias with the single destination behind it:

registry: ~/.config/brama/inference-routes.json
deployments: 1
routes: 3
best                             best
weles                            local-openai/chat-primary
wisent-backend                   openai/gpt-4o-mini

With --json the answer is one object, {"registry", "document"}, whose document is the migrated registry as it now stands on disk. Exit code is 0 on success. The command is idempotent: a document already in this shape is validated, written back identically, and reported the same way, so it is safe in a provisioning run that cannot know what shape the file is in.

Refusals¶

route migration error: <reason> on standard error, exit 1, when the file cannot be read, the retained document does not validate, or the replacement cannot be written. The reason is the registry's own sentence — the parser's message, one of the file-ownership and mode requirements, an alias repeating a destination, or a deployment with no safe loopback or Tailscale endpoint. The original file is untouched in every one of those cases. Clap refuses unsupported options before any file is opened.

After migrating¶

Read the result with brama aliases: every alias should report serving, or no_route and capability_absent for the reasons those states name. The running gateway needs no restart, because it re-reads the registry per request.

See the route registry, aliases, or the CLI tree.