Wayfinder Router: a deterministic model router for local and hosted LLMs

The problem Wayfinder Router addresses: too many models, no stated rule

Most developers who use LLMs now have more than one option on the same machine. There is a local runtime on loopback, a subscription-backed model behind an account, and at least one API key in an environment file. Choosing between them per request is usually done by hand, or by a client that hard-codes a single endpoint. Neither approach produces a record of why a given prompt went where it went.

Wayfinder Router targets that gap. The README describes it as a tool that "selects an eligible local, account-backed, or API model for each request, then records a deterministic receipt explaining the choice." The audience is narrow and stated plainly: Omarchy developers first, and anyone else who wants a portable Rust router underneath. The scored decision path is offline, deterministic and keyless. That last property is the design commitment worth noting: the router does not need a credential to decide, only to deliver.

How the scored decision path works and where credentials enter

The architecture separates two phases. First, a configuration parser and a scoring core evaluate the request against the policy. The README says the router "discovers model IDs only from fixed loopback catalogs and proves a loaded model with one bounded public inference probe." So discovery is not a scan of the network; it is a fixed set of local addresses, plus a single probe to confirm a model is actually loaded.

Second, delivery. Once a route is chosen, credentials are resolved. The README is explicit that the scored decision "remains offline, deterministic, and keyless; credentials are resolved only for delivery after the route is chosen." That ordering matters for anyone auditing the system: the scoring code never sees a key.

The gateway exposes an OpenAI-compatible surface at `http://127.0.0.1:8088/v1`, an Anthropic-compatible surface at `http://127.0.0.1:8088`, and health at `http://127.0.0.1:8088/healthz`. There is also a bounded OpenAI Responses compatibility endpoint at `POST /v1/responses`, described as covering the text, multi-turn and function/custom tool contract used by Codex. The README states that non-text surfaces (embeddings, image, audio, batch) remain fail-closed until their reviewed adapters are enabled, which is a deliberate choice: an unimplemented modality returns an error rather than a silent fallback.

One constraint to internalise: the router never downloads, pulls, selects, or activates a model silently. If you expect it to fetch weights for you, it will not. It routes among what is already there.

Building Wayfinder Router from the Rust workspace and scoring a first prompt

The portable path needs a Rust toolchain. The README gives this build command, which pins the lockfile:

cargo build \
  --manifest-path rust/Cargo.toml \
  --package wayfinder-cli \
  --bin wayfinder-router \
  --locked

After that, the binary lands in `rust/target/debug/`. The README's first real use is a single route command, which scores a prompt and prints a recommendation:

rust/target/debug/wayfinder-router route "Summarise this request"

To run the gateway instead of a one-shot score, the README gives:

rust/target/debug/wayfinder-router serve --host 127.0.0.1 --port 8088

The Makefile wraps the same steps if you prefer targets: `make build` runs the locked Cargo build, and `make route PROMPT=path/to/prompt.md` builds first and then routes the file. The repository also ships a `docker-compose.example.yml` and a sample policy at `examples/wayfinder-router.lexical.toml`, which is the fastest way to see the shape of a policy before writing your own.

If you are on Omarchy, the README points at a different entry point entirely: install the plugin and use the native setup flow, which installs the checksum-pinned Router, creates a policy, validates it, and starts the user service. That path is documented as needing no Rust, Cargo, hand-written unit file, or copied endpoint.

Connecting coding agents, and the one that stays on the reviewable path

The README names Codex, Claude Code, OpenCode, Pi, and Aider as clients that can be pointed at the same loopback policy with `wayfinder-router connect <client>`. There is a documented quick-start file at `docs/coding-agent-quickstarts.md` for the verified cases, and `wayfinder-router open` inspects local routing decisions.

A second launcher exists for Omarchy: `wayfinder-router exec <client> -- <program>`. The README describes it as a no-write launcher that validates Router readiness and the client's wire capability first, applies only process-local endpoint, model and placeholder-token overrides, and never falls back to the direct provider. The no-fallback rule is the interesting part. A launcher that silently bypasses the router when the router is down would produce usage that never appears in the receipts.

Pi is deliberately excluded from that launcher. The README says Pi remains on the reviewable `connect` path until its CLI exposes a verified no-write endpoint override. That is a project admitting a client limitation rather than papering over it, and it tells you the `exec` path depends on a property of the client, not just of the router.

The managed data plane and what the container image does not do

For a network-exposed deployment the README warns against publishing the local surface and instead describes a managed data plane. You mint a virtual key and start the managed listener:

rust/target/debug/wayfinder-router keys new --id team-a
rust/target/debug/wayfinder-router serve \
  --surface data-plane --host 0.0.0.0 --port 8088

The managed listener contains inference, authenticated model discovery, and the `/livez` and `/readyz` probes only. The Dockerfile confirms the container's default command starts that surface: `wayfinder-router serve --surface data-plane --host 0.0.0.0 --port 8088 --config /etc/wayfinder/wayfinder-router.toml`.

The image runs as UID/GID 10001, expects config at `/etc/wayfinder/wayfinder-router.toml` via `WAYFINDER_CONFIG`, and writes audit and savings state to `/var/lib/wayfinder` through `WAYFINDER_ROUTER_AUDIT_FILE` and `WAYFINDER_ROUTER_SAVINGS_FILE`. Configuration is read-only; state is not. The README notes the container requires at least one virtual key and one model in the config, which means the image will not start usefully against an empty policy. The `--read-only` and `--tmpfs /tmp` flags in the README's run example are consistent with that split, but the README does not document what happens when the state volume is missing or unwritable.

Where Wayfinder Router is the wrong tool

Three cases stand out. First, if you want a router that manages model lifecycle, this is not it. The README states the router never downloads, pulls, selects, or activates a model silently, so provisioning weights stays your job.

Second, if your client cannot be redirected to a loopback endpoint, the `connect` and `exec` paths do not help you. The router's value depends on traffic actually passing through it, and the no-fallback design means a client that ignores the override simply bypasses routing.

Third, the documentation has real gaps. The README does not document rollback for a policy change, and it does not describe what the savings file contains beyond its path. The macOS desktop app, the iPhone and iPad work, and the Omarchy plugin are all described in the README, but only the Omarchy plugin and the portable Router are backed by the release tags in this repository: `router-v1.1.0`, `router-v1.0.0`, and `router-v2026.8.1` are the recent releases, and the README says Desktop releases use separate `desktop-v*` tags. The mobile roadmap is explicitly paused. If you are evaluating the whole product family from the release list alone, you will overestimate what is shipping.

A note on the search terms people use: queries like "Wayfinder Laravel", "Wayfinder Inertia" and "Vite plugin wayfinder" refer to unrelated projects that share the name. This repository is a Rust model router and has nothing to do with Laravel, Inertia or Vite.

Alternatives and the actual difference in approach

The obvious comparison is a general-purpose LLM proxy such as LiteLLM, which the repository acknowledges indirectly by shipping `examples/librechat.yaml` for a chat front end. A proxy of that kind is configured with model lists, fallbacks and retry rules, and it routes by declared policy, often with cost and rate-limit weighting. Wayfinder Router instead scores the prompt itself and produces a receipt for the decision. The difference is where the rule lives: in a static config table versus in a scoring pass over the request.

A second comparison is a client-side model picker, the kind built into an editor or agent CLI. That keeps selection inside the tool, which is simpler but gives you no shared endpoint and no cross-client record. Wayfinder Router's bet is that one loopback policy shared by Codex, Claude Code, OpenCode, Pi and Aider is worth the extra process.

A third option is writing your own thin proxy. That is genuinely small work if all you need is an endpoint swap, and it avoids a new dependency. What you would have to rebuild is the deterministic scoring plus the receipt, which is the part this project exists to provide.

Licence, maintenance and the cost of upgrading

The repository is Apache-2.0, with a `LICENSE` and a `NOTICE` file at the top level. Apache-2.0 includes an express patent grant and requires attribution and notice retention, which matters if you redistribute the binary or embed the workspace. The README does not offer legal guidance, and neither does this article; if you are shipping the router inside a product, read the licence text and the NOTICE yourself.

The last push to the default branch was on 2026-09-06, the same day as the `router-v1.1.0` release, and the repository is not archived. Releases are frequent enough that the tag scheme matters: `router-vMAJOR.MINOR.PATCH` for the Router, and a separate `desktop-v*` line for the macOS app. The README states the Linux archives for `x86_64` and `aarch64` are checksum-verified, and that installing an archive does not create or start a service or alter provider credentials. That is the upgrade path to plan around: replacing a binary is cheap, but the policy file and the state volume are yours to migrate, and the README does not describe a migration story for either. The verification commands in the README are `cargo fmt --manifest-path rust/Cargo.toml --all -- --check` and `cargo test --manifest-path rust/Cargo.toml`, and the Makefile adds a clippy target that treats warnings as errors with `-D warnings`.

Editorial conclusion

Adopt Wayfinder Router if you run several local and hosted models on one machine and want the routing decision to be inspectable rather than probabilistic, and if you are willing to read the policy file before trusting it. Skip it if you need a hosted multi-tenant control plane, if you expect the router to pull models for you (it does not), or if your client cannot be pointed at a loopback endpoint. Before wiring anything real, build the binary with the locked Cargo command, run `wayfinder-router route` on a few representative prompts, and check what the receipt says about the model it chose and why.

Frequently asked questions

Official sources

1. asdecided/WayfinderRouter on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases