steipete--codexbar/docs/wayfinder.md

summary, read_when

summary	read_when
Wayfinder setup for local gateway health, per-route breakdown, and savings.	Configuring Wayfinder usage tracking Debugging Wayfinder gateway health or savings display Explaining the Wayfinder gateway URL setting

Wayfinder

Wayfinder is a self-hosted, deterministic local/cloud LLM router. Its gateway runs on the user's machine (default http://127.0.0.1:8088) and scores each prompt offline — no model call — to decide whether the cheap/local or the dearer/cloud tier serves it. CodexBar polls the gateway's read-only JSON endpoints and shows whether the gateway is up, how traffic split across the configured routes, what that saved versus routing everything to the dearest tier, and the average routing decision time.

The integration is read-only. CodexBar never sends prompts through the gateway, never calls its chat endpoints, and the endpoints it polls return accounting metadata only — Wayfinder's API never exposes prompt text.

Setup

Wayfinder's read-only endpoints are unauthenticated on loopback, so there is nothing to log in to: enable the provider in CodexBar Settings → Providers → Wayfinder. The default gateway URL is used unless you override it:

http://127.0.0.1:8088

If your gateway listens elsewhere, set the Gateway URL in Settings or export WAYFINDER_GATEWAY_URL. Overrides must be HTTPS, or plain HTTP for loopback addresses only (localhost, 127.0.0.0/8, ::1) — the gateway is a local service and remote plain-HTTP endpoints are rejected.

Display

• Gateway health: ok or degraded (with the number of models missing API keys), plus offline-mode and dry-run markers.
• Routing split over the last 30 days: requests per configured route (up to 5, by request count), using each route's own name from the Wayfinder config — the gateway has no field asserting which route is "local," so CodexBar never guesses.
• Savings over the last 30 days versus routing everything to the dearest tier, with the percentage. Dollar amounts appear only when the gateway config prices its models (cost_per_1k); unpriced gateways report a relative percentage only.
• Average routing decision time, parsed best-effort from the gateway's Prometheus /metrics endpoint. Decisions are computed offline, so this is typically well under a millisecond.

Endpoints polled

Endpoint	Purpose
GET /healthz	Gateway status, configured models, offline flag, missing keys.
GET /router/models	Configured model count and dry-run flag.
GET /v1/savings?period=30d	Requests, tokens, realized/baseline cost, savings, per-route split.
GET /metrics	Decision-latency histogram for the average routing time (best effort).

Environment variables

Variable	Description
WAYFINDER_GATEWAY_URL	Optional gateway URL override (HTTPS, or loopback HTTP).

If the gateway is not running, CodexBar reports that it could not be reached and suggests starting it with wayfinder-router serve.