f3router docs

f3router docs

f3router runs on your machine and gives your coding agents one OpenAI-compatible /v1 endpoint in front of many free LLM providers.

Install

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/f3tools/f3router/main/docs/install.sh | sh

Windows

irm https://raw.githubusercontent.com/f3tools/f3router/main/docs/install.ps1 | iex

Or download the desktop app from GitHub Releases. The installer scripts are in the repository under docs/.

The app prints its local address when it starts. Use that address and port in the steps below.

Connect an agent

Point your agent at the router instead of a provider:

  • Base URL: http://localhost:<port>/v1 for OpenAI-style clients
  • API key: the f3router key shown in the app (not a provider key)
  • Model: auto lets the router choose, or pick a specific model id from the Models page

Anthropic-style clients can use the same server root. Check the Keys page in the app for the exact values.

Provider keys

Add keys for the free-tier providers you have accounts with. Each key is stored encrypted on your machine and used only for that provider.

  • Keys stay on your machine. Nothing is sent to f3tools.
  • Rotate or remove a key at any time from the Keys page.
  • Per-key usage is tracked so the router can stay under each free-tier cap.

Routing

The router ranks the models you have keys for and tries them in order:

  • Balanced (default): weighs reliability, speed and intelligence.
  • Manual: you set the order by dragging models.
  • Fastest, Smartest, Most reliable, Custom: other live-score strategies.

If a provider returns a rate limit or an error, the router cools it down and tries the next one. Failovers and scores are visible per request in Analytics.

Self-hosting

f3router is single-user software. Keep it bound to localhost unless you know you need LAN access. Install and architecture details are in the repository guides:

Troubleshooting

  • "No active credentials for provider": the model's provider has no key yet. Add a key for it on the Keys page.
  • Agent cannot connect: check the base URL includes /v1 and the port matches what the app shows.
  • Every request falls back: open Analytics to see which providers are cooling down and why.

Every topic is in the full docs: install, clients, providers, routing, environment variables, API, deployment and troubleshooting.

License

f3router is MIT licensed. See LICENSE in the repository.