Architecture and request flow
How the RouteKit CLI, singleton daemon, gateway, and provider routes work together.
RouteKit gives coding tools and HTTP clients one stable endpoint while keeping every model attached to its configured provider, credential owner, billing mode, protocol, and quota.
How RouteKit routes a request
A canonical model ID has the form provider/native-model. RouteKit sends an
explicit request only through that namespace. An unavailable subscription
route does not silently invoke a metered API-key route.
CLI and daemon responsibilities
The routekit CLI edits configuration, enrolls accounts, inspects state, and
connects clients. One singleton daemon per ROUTEKIT_HOME owns:
- provider authentication and model discovery;
- subscription pools and quota state;
- the canonical router configuration;
- model-call attribution and optional durable rollups;
- the local gateway, which binds to
127.0.0.1:8080by default.
Product commands start the daemon race-safely when needed. RouteKit uses a systemd user service or launchd agent when available and reports a detached process fallback otherwise.
Gateway and management planes
Model clients use the bearer-token-authenticated data plane. The CLI uses the
private control.v1 management plane for configuration and operations.
/health is the only intentionally unauthenticated gateway endpoint.
Remote installations keep the control plane on the host and relay management operations through SSH. Model traffic reaches an operator-provided HTTPS data plane. Read remote gateways for the trust model.
What happens when configuration changes
The daemon reads one canonical document at
~/.config/routekit/router.yaml. Configuration and account mutations replace
the active router generation atomically. Existing streams receive a grace
period to drain, so a reload does not move a request midway through a response.
The installed daemon is a stable Node cluster primary plus one active worker. The primary owns singleton authority, service records, shared control/data ports, Portless registration, and the managed CLIProxyAPI sidecar. The worker owns control handlers, account state, telemetry, the switching proxy, and its ephemeral router generation. Restart and upgrade prepare a candidate worker on the same shared ports, synchronize revisions while mutations are briefly paused, commit the candidate, and retire the previous worker. A failed candidate does not change the service record or interrupt the active worker.
Every configured provider must authenticate and discover models. Startup fails instead of silently dropping a broken provider.