Providers & Models

Configuration reference

Everything about providers lives under the providers key in ~/.flowly/config.json. You normally never edit this by hand — /provider, /model, and flowly setup byok write it for you — but here's the full shape.

The providers block

Keys are camelCase on disk. A representative config:

json

{
  "providers": {
    "active": "openrouter",          // explicit default ("" = use the cascade)

    "flowly": {                      // Flowly Cloud (hosted credits)
      "enabled": true,               // on by default; auth comes from your account
      "apiBase": "https://useflowlyapp.com/api/v1"
    },

    "openrouter": {                  // BYOK slots: apiKey (+ optional apiBase)
      "apiKey": "sk-or-...",
      "apiBase": "https://openrouter.ai/api/v1",
      "fallbackKeys": []
    },
    "anthropic": { "apiKey": "" },
    "openai":    { "apiKey": "" },
    "xai":       { "apiKey": "", "apiBase": "https://api.x.ai/v1" },
    "gemini":    { "apiKey": "" },
    "groq":      { "apiKey": "" },
    "zhipu":     { "apiKey": "" },
    "vllm":      { "apiKey": "", "apiBase": "" }
  },

  "agents": {
    "defaults": { "model": "moonshotai/kimi-k2.5" }   // the active model id
  }
}

Field reference

providers.active — the explicit default provider slug. When set and usable it overrides the cascade. Empty string means “use the priority cascade.” How the cascade works.
providers.flowly.enabled — turn Flowly Cloud on or off. There's no apiKey here; auth comes from your signed-in account.
providers.<name>.apiKey — the BYOK API key for that provider.
providers.<name>.apiBase — override the endpoint URL. Needed for vllm and custom / self-hosted endpoints; optional elsewhere.
providers.<name>.fallbackKeys — extra keys to rotate through when the primary one is rate-limited or failing.
agents.defaults.model — the model id used for the next request. Short names (sonnet, opus) or full ids both work.

Selecting the model

The active model is a single value: agents.defaults.model. The easiest way to set it is /model, which writes a valid id for the active provider. Set by hand only if you know the exact id the provider expects:

json

{ "agents": { "defaults": { "model": "anthropic/claude-sonnet-4.6" } } }

Model ids must match the provider exactly

An id that's valid on one provider may not exist on another. When you switch providers, re-pick the model with /model rather than carrying the old id over.

Key rotation & fallbacks

For BYOK providers, fallbackKeys lets Flowly ride out rate limits and dead keys without dropping a request. The primaryapiKey is tried first; on failure Flowly moves to the next key in the list, and a failed key enters a short cooldown before it's retried.

json

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-primary",
      "fallbackKeys": ["sk-or-backup-1", "sk-or-backup-2"]
    }
  }
}

Custom endpoints (apiBase)

Set apiBase to route a provider through a custom URL — a self-hosted model server, an OpenAI-compatible proxy, or a regional gateway. The vllm slot exists specifically for this:

json

{
  "providers": {
    "active": "vllm",
    "vllm": { "apiKey": "EMPTY", "apiBase": "http://localhost:8000/v1" }
  },
  "agents": { "defaults": { "model": "your-served-model-id" } }
}

Where keys are stored

Provider API keys live in ~/.flowly/config.json on your own machine. Treat that file as a secret — it isn't synced anywhere by Flowly. Flowly Cloud needs no key at all; its auth is your signed-in account, stored separately in your credentials.

Verify what's active any time

/whoami in the terminal chat shows the signed-in account and the resolved active provider — the quickest way to confirm your configuration is doing what you expect.