Overview

A model source is wherever your tokens actually come from. Routeplane puts every source behind one endpoint and one registry, so an agent addresses models by their provider/model id and never sees the difference between a subscription, an aggregator, and a GPU in your closet.

There are three shapes of source, by how you authenticate:

How a source is wired

Source	Auth	Where it’s configured
Subscriptions (Claude, Codex)	OAuth: your plan’s login	routeplane providers login <provider> (no API key)
Aggregators / hosted (OpenRouter, …)	Bring-your-own API key	A provider block in routeplane.yaml
Self-hosted (Ollama, vLLM)	Usually none (loopback)	A provider block in routeplane.yaml

Subscription login uses dedicated providers such as claude-code and openai-codex. Run routeplane providers login <provider> first. A default label can auto-enable its provider; a named label must also appear under that provider’s accounts: config. Everything else is a provider block: an api_base, an optional api_key, and the models that source serves.

routeplane.yaml

providers:
  openrouter:                          # an id you pick (or a built-in id)
    api_base: https://openrouter.ai/api/v1
    api_key: ${OPENROUTER_API_KEY}     # resolved from the environment at load
    api_protocol:
      - "*": chat_completions          # upstream wire format
    models:
      - id: openai/gpt-4o

providers is a map keyed by an id you choose; api_base is the source’s base URL; api_protocol is the upstream wire format (chat_completions for any OpenAI-compatible host: also the inferred default); each models entry is a model that source serves.

Scaffold a config

Generate a starter routeplane.yaml (defaults to ./routeplane.yaml):

routeplane init

This writes a commented config with skip_auth: true, ready for a provider block. Use -c <path> to write it elsewhere, then follow your source’s page to fill in the block. Subscription login uses routeplane providers login; a non-default account label must also be listed under that provider’s accounts: config.

Start Routeplane and send a request

Once your source is wired (a provider block in place, or a subscription logged in) start the proxy. It listens on 127.0.0.1:4356 by default:

routeplane

Then hit the OpenAI-compatible endpoint with a model id from your config (swap in your provider id / model):

curl http://localhost:4356/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter:openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello from Routeplane"}]
  }'

The bare model name also works. Routeplane auto-cascades it to whichever active source declares it. The provider-qualified form (openrouter:openai/gpt-4o) pins the request to that exact source.

**Mix sources freely.** Declare a [virtual model](/features/model-fallback) whose endpoints list a local source first and a hosted one second: requests run on your own hardware for free and fail over to the hosted model on error or overload: one model name, automatic failover.

For the concepts behind this (provider selection, fallback, and registry detection) see Models. To serve models yourself, see the local-server integrations: Ollama and vLLM.