//Quickstart

About ten minutes. Everything after the install happens in the dashboard.

  1. 1 · Install

    Needs Python 3.11 or newer.

    terminal
    pip install flexrouter

  2. 2 · Open the dashboard

    This starts flexrouter in the background and opens the dashboard in your browser. Leave it running.

    terminal
    flexrouter dashboard

  3. 3 · Add a free provider

    On the Get started card, pick a provider marked free tier, follow its Get a key link, and paste the key. The step ticks itself when the key works. Add a second provider the same way: more providers means more free usage.

  4. 4 · Add models, then Test all

    Press Add models with AI to find the models your keys can use and put them in buckets. Then press Test all: it says hi to every model once and shows which ones answer.

  5. 5 · Point your app at it

    Anything that can talk to OpenAI's API works. Use http://localhost:4891/v1 as the address and a bucket name, like smart, wherever it asks for a model.

    curl
    curl http://localhost:4891/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "smart", "messages": [{"role": "user", "content": "hi"}]}'
    python, OpenAI SDK
    from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4891/v1",
    api_key="your app password from Settings",
)
reply = client.chat.completions.create(
    model="smart",  # a bucket name, not a model
    messages=[{"role": "user", "content": "hi"}],
)
print(reply.choices[0].message.content)
Prefer editing the settings file by hand?

Run flexrouter doctor to see where your settings file is. flexrouter reads it but never rewrites it, and your keys never go in it (save them with flexrouter keys add groq).

config.yaml
providers:
  groq:
    base_url: https://api.groq.com/openai/v1

buckets:
  smart:
    - provider: groq
      model: openai/gpt-oss-120b
      score: 85
      rpm: 30
      tpm: 8000
      context_window: 131072
Calling it from Python without the web address

For Python code that would rather call flexrouter directly. It uses the same settings.

python
from flexrouter import FlexRouter

router = FlexRouter()
reply = router.generate(
    messages=[{"role": "user", "content": "Summarise this in one line."}],
    tier="smart",
)
print(reply["choices"][0]["message"]["content"])

Next, the Getting Started guide walks through all of this in more detail. The other guides are in the flexrouter repository.