Configuration

Two configuration owners

FusionKit v4 separates fusion policy from model routing:

• .fusionkit/fusion.json defines ensembles, prompts, and Fusion behavior.
• .routekit/router.yaml explicitly enables providers and configures pooling policy.

FusionKit sees namespaced provider/model IDs from RouteKit's live catalog. RouteKit never sees ensembles.

fusionkit init

This creates Fusion config and, when absent, a safe provider-based RouteKit placeholder. Install @velum-labs/routekit separately if you want its provider, catalog, and account commands; FusionKit does not depend on that executable.

FusionKit v4 schema

{
  "version": "fusionkit.fusion.v4",
  "router": { "config": ".routekit/router.yaml" },
  "tool": "codex",
  "defaultEnsemble": "default",
  "ensembles": {
    "default": {
      "members": ["openai/gpt-5.5", "anthropic/claude-sonnet-4-5"],
      "judge": "anthropic/claude-sonnet-4-5",
      "synthesizer": "anthropic/claude-sonnet-4-5",
      "k": 1
    }
  },
  "observe": false,
  "onRateLimit": "fusion",
  "budgetUsd": 5,
  "panelTrust": "full",
  "reasoning": true,
  "subagents": true,
  "portless": true
}

router sets exactly one of:

• config: start an embedded RouteKit router owned by the Fusion process.
• url plus optional authEnv: connect to an external RouteKit gateway. FusionKit validates its /v1/models list and never stops it.

Standalone RouteKit configuration

The standalone routekit CLI is a thin client of one singleton daemon. That daemon reads exactly one canonical document: ~/.config/routekit/router.yaml. It never discovers or layers a project file from the caller's working directory because concurrent projects share the same gateway.

Project .routekit/router.yaml files remain valid as explicit inputs to FusionKit embedded mode and the embeddable RouteKit SDK. To migrate one into the singleton daemon, replace the complete canonical document explicitly:

routekit config import --from .routekit/router.yaml

Import validates and atomically replaces the canonical document; it does not merge project and global files. Expand any sparse SDK overlay that depends on inherited global fields into a complete router document before importing it. Stop any foreground gateway running from an explicit config before replacing the canonical singleton document. Daemon-backed commands reject --config and ROUTEKIT_CONFIG; those selectors are limited to documented foreground gateway, doctor, migration, and SDK recovery paths.

Ensemble members, judge, and optional synthesizer values are namespaced IDs advertised by RouteKit's live catalog. Provider policy, credentials, registry URLs, pricing, and subscription-account enrollment are rejected here.

RouteKit router

Enable API providers explicitly. RouteKit obtains URL and credential metadata from its registry and performs live discovery at startup:

providers:
  openai: {}
  anthropic: {}
defaultModel: openai/gpt-5.5

Subscription providers use the same map and carry account-selection policy:

providers:
  claude-code:
    strategy: capacity_weighted
    switchThreshold: 0.9
  codex:
    strategy: capacity_weighted
    switchThreshold: 0.9
defaultModel: codex/gpt-5.5

routekit accounts login claude-code --name personal
routekit accounts login claude-code --name work
routekit models list
routekit claude claude-code/claude-sonnet-4-5

The first successful managed login or explicit routekit accounts add import enables that provider in the singleton's canonical router config. RouteKit discovers each healthy member, publishes the union, and routes a model only to accounts that advertise it. Quotas, refresh, cooldowns, and reset windows remain per account.

Inline API keys and authorization tokens are rejected. Omitting a model uses the configured default/first live model; an explicit unknown or unnamespaced ID is rejected and never default-routed. Discovery failure for any configured provider fails startup.

Edit and inspect

fusionkit config show
fusionkit config get budgetUsd
fusionkit config set budgetUsd 5
fusionkit config set ensembles.default.judge anthropic/claude-sonnet-4-5
fusionkit config unset budgetUsd
fusionkit config edit

fusionkit ensemble add review \
  --member openai/gpt-5.5 \
  --member anthropic/claude-sonnet-4-5 \
  --judge anthropic/claude-sonnet-4-5

Precedence is CLI flag, then .fusionkit/fusion.json, then built-in default. All writes are validated and atomic.

Prompt files

Use .fusionkit/prompts/judge.md and synthesizer.md. A .fusionkit/prompts/<ensemble>/ file overrides the flat prompt for that ensemble. Manage them with fusionkit prompts list|edit|reset.

Migrating from v3

v1-v3 files are not silently dual-read. Run routekit --config <legacy-router-path> config migrate for the specific project file, replace opaque aliases with namespaced provider/model IDs from the provider's catalog, validate the embedded project with fusionkit doctor, and set fusionkit.fusion.v4. For an external singleton, import the complete migrated router before inspecting it with routekit models list. Runtime loading rejects legacy endpoints, accounts, and defaultEndpointId fields.