Bring existing configuration¶

An existing Brama installation can seed a new one before any provider request. The adoption review reads a route registry document, shows you exactly what it would write, and writes only what you select.

Start the review¶

brama adopt --from /path/to/inference-routes.json
brama onboard --model <ROUTE> --agent-id <ID> --adopt-from /path/to/inference-routes.json

Both are documented under brama adopt. Brama Desktop offers the same Review existing setup… action during first use and under Settings → Existing configuration. Both surfaces call the Brama service's configuration-adoption operation and its owner-only route registry; the desktop neither parses nor writes routes on its own.

The document being read¶

A route registry document carries exactly three known top-level fields: schema_version, whose value is the number one, plus deployments and routes. routes maps an alias to its single destination. The example below omits the schema_version line for the docs build; a real file carries it with the version stated in the previous sentence.

{
  "deployments": {
    "llama-local": { "backend": "llama.cpp", "model": "llama-3.1-8b" },
    "claude-direct": { "provider": "anthropic", "model": "claude-sonnet" }
  },
  "routes": {
    "fast": "llama-local",
    "deep": "claude-direct"
  }
}

An unknown top-level field is refused by the deserializer, and the whole document is rejected rather than partly read. An older file that still carries extra top-level fields reaches this shape with brama routes migrate: it keeps only the known fields, validates the result, commits it with the same atomic owner-only replacement every other registry write uses, prints the resulting document, and is idempotent, so running it twice changes nothing the second time. Run it on the source file before the review when the review rejects the document.

What the review reports¶

The review lists, for each alias in the source document:

• the alias name and its single source route;
• the alias's current destination in this installation when the alias already exists here;
• whether the referenced deployment is present locally;
• the direct-provider acquisitions already configured for this Brama runtime;
• subscription identities discovered through the existing Skarbiec boundary for the selected agent.

One alias means one route on both sides of the comparison, so each row is a single pair: source route against current route. Deployments in the source document that no alias references are reported as unreferenced; they are never imported unless you select them.

The review never requests or copies credential contents, never enables a subscription, and never calls a model.

Selection and conflicts¶

Nothing is selected for you. A missing or empty source is reported as exactly that. Declining the review leaves an empty but usable setup. Applying a selection validates the complete source and destination first, then performs one atomic write.

• Same route: an alias whose source route equals its current route is reported unchanged and is not rewritten.
• Different route: a source route that differs from the alias's current route is a conflict. The current route stays in place unless that exact alias was selected with --replace-conflicts, in which case the source route becomes the alias's single destination.
• Deployment name conflict: a source deployment whose name already exists locally is never replaced; the local deployment stands and the alias that needed the source definition is reported as rejected.

Aliases, deployments, credentials, and the source file you did not select remain exactly as they were.

What success means here¶

Successful persistence reports imported, unchanged, conflicting, and rejected aliases, and the committed document is the one the service will read. That advances the configuration step, but it is not Brama's first success: the journey stays in progress until the gateway produces a real routed model response, described in first success.

After the write, confirm the result with brama aliases, which prints alias, state and route, or with GET /v1/aliases, whose rows carry alias, state, route, reason, required and authorized. An alias reported capability_absent or no_route needs the repair named in failures and reset.