Router-Maestro

CI Release PyPI

Use the full GitHub Copilot model catalog from Claude Code, OpenAI Codex, Gemini CLI, and any OpenAI-, Anthropic-, or Gemini-compatible client.

Router-Maestro is a local or self-hosted model gateway. It separates the client protocol from the upstream model transport, so a client is no longer limited to models that natively speak its API. Claude Code can use Responses-only GPT models; Codex can use Claude, Gemini, Grok, and MAI models; Gemini CLI can use the same catalog through its native API surface.

https://github.com/user-attachments/assets/35f7c0f5-967a-4f93-aec8-c34b460a0032

Why Router-Maestro

  • One Copilot subscription, every compatible client. Authenticate once with GitHub Copilot and expose its live catalog—including GPT, Claude, Gemini, Grok, and MAI—to Claude Code, Codex, Gemini CLI, and API clients.
  • Protocol-independent routing. Anthropic Messages, OpenAI Chat Completions, OpenAI Responses, and Gemini generation enter one dispatcher; providers choose the best Messages, Chat, or Responses upstream transport.
  • Native fast paths, translation only when needed. Matching protocols use a copy-on-write identity path. Cross-protocol attempts lazily materialize a typed semantic representation and stream events without buffering the full response.
  • Tools, streaming, reasoning, and long context. Router-Maestro preserves tool calls/results, structured output, usage, terminal outcomes, and reasoning continuation across supported protocol boundaries. Live catalog metadata advertises context choices such as 272K / 1M to clients.
  • A real Auto model. The virtual router-maestro model can classify work into Fast, General, Coding, or Deep Reasoning tasks, or follow a strict priority chain. Capability and context-window filtering happen before the model is selected.
  • Configuration for humans and agents. Use searchable CLI wizards or the loopback-only visual portal to manage contexts, models, context windows, client configuration, trusted projects, and Auto routing.
  • Self-hosted control. Run locally, in Docker, or behind HTTPS. Prometheus metrics, request IDs, stream guards, and opt-in audit traces support production diagnosis without sending routing control to a hosted portal.

Supported Surface

Clients and ingress protocols

Client or API consumer Router-Maestro surface Full Copilot catalog
Claude Code / Anthropic SDK Anthropic Messages Yes, including Responses-only GPT models
OpenAI Codex / OpenAI SDK OpenAI Responses Yes, including Claude, Gemini, Grok, and MAI
OpenAI-compatible clients Chat Completions Yes, subject to feature representability
Gemini CLI / Gemini SDK Gemini generateContent Yes, across available upstream transports

Providers

Provider Authentication Upstream transports
GitHub Copilot OAuth device flow Messages, Chat, Responses as advertised by each model
OpenAI API key OpenAI-compatible transport
Anthropic API key Anthropic Messages
Custom OpenAI-compatible API key, environment key, or explicit anonymous mode Chat Completions

Unsupported cross-protocol fields fail explicitly before provider I/O rather than being silently dropped.

How It Works

flowchart LR
    C[Claude Code / Codex / Gemini / SDK] --> P[Protocol runtime]
    P --> R[Model and Auto routing]
    R --> H[Provider handler]
    H --> T{Best upstream transport}
    T -->|same protocol| I[Identity fast path]
    T -->|cross protocol| S[Lazy semantic translation]
    I --> U[Provider model]
    S --> U

Provider handlers own their catalog, authentication, endpoint bindings, transport preference, and provider-specific contracts. Routing selects a model; the handler selects how to call it. Model fallback begins only after the selected model's viable transports are exhausted.

Five-Minute Local Start

Prerequisites:

  • uv or another Python 3.14 package installer
  • an active GitHub Copilot subscription for Copilot-backed models

Install the CLI and server:

uv tool install --python 3.14 router-maestro

Start Router-Maestro in one terminal:

router-maestro server start

The first start creates a local context and a sk-rm-... server API key. In a second terminal, authenticate and open the visual configurator:

router-maestro auth login github-copilot
router-maestro web

Or configure a client from the terminal:

router-maestro config claude-code
router-maestro config codex
router-maestro config gemini

The wizard reads the active server's live model catalog, lets you choose the model and context window, and previews or backs up the target configuration. For Codex it can also refresh router-maestro-models.json, so custom model metadata is available when the next Codex session starts.

Verify the server and catalog:

curl http://localhost:8080/health
router-maestro model list

For Docker, a VPS, HTTPS, upgrades, and rollback, follow the Deployment Guide. For all client and provider choices, follow the Configuration Guide. Both guides include prompts that can be pasted directly into an AI coding agent.

To delegate the work, start at AI-assisted deployment or AI-assisted client configuration.

Router-Maestro Auto

Select the virtual model ID router-maestro to enable server-side automatic routing. New configurations default to Smart Auto:

  1. A configured router model classifies the request as fast, general, coding, or deep_reasoning.
  2. The corresponding configured task model becomes the first candidate.
  3. Capability requirements and the estimated input size filter unsafe models. Router-Maestro normally keeps candidates below 70% of their advertised prompt capacity to leave room for tokenizer and protocol differences.
  4. If no model satisfies that safety margin, all configured models tied for the largest hard-compatible context window remain eligible.
  5. A precise upstream context-overflow response may retry a larger configured model before the first response frame; committed streams are never replayed.

Priority Chain mode is available when deterministic ordering is preferred. Its configured fallback chain must not be empty.

Configure either mode with:

router-maestro model auto configure
# or
router-maestro web

See Auto routing and client configuration for policy details.

Stable API Endpoints

New integrations should use the stable paths:

API Endpoint
OpenAI Chat Completions /api/openai/v1/chat/completions
OpenAI Responses /api/openai/v1/responses
OpenAI model list /api/openai/v1/models
Anthropic Messages /api/anthropic/v1/messages
Anthropic token count /api/anthropic/v1/messages/count_tokens
Gemini generation /api/gemini/v1beta/models/{model}:generateContent
Gemini streaming /api/gemini/v1beta/models/{model}:streamGenerateContent

0.9 to 1.0 endpoint migration

0.9 is the final minor release before 1.0. The following Router-Maestro beta aliases remain available only for the 0.9 migration window and will be removed in 1.0.0:

Deprecated 0.9 compatibility alias Stable replacement
/api/openai/beta/v1/responses /api/openai/v1/responses
/api/anthropic/beta/v1/messages /api/anthropic/v1/messages
/api/anthropic/beta/v1/messages/count_tokens /api/anthropic/v1/messages/count_tokens

Move client configuration to the stable paths before upgrading to 1.0.0. /api/gemini/v1beta is the Gemini protocol version, not a Router-Maestro beta route, and is not part of this removal.

Authenticated inference and administration use the same Router-Maestro server API key. /health is public. /metrics is public unless a separate metrics token is configured. Treat the server key as both inference and configuration authority.

Documentation

Use and operations

  • Configuration Guide — contexts, providers, CLI and Web configuration, Claude Code, Codex, Gemini CLI, Auto, and AI-agent prompts
  • Deployment Guide — native, Docker, VPS, Traefik/HTTPS, upgrades, rollback, multi-instance keys, and AI-agent prompts
  • Metrics and Observability — Prometheus metrics, request IDs, terminal outcomes, audit artifacts, and troubleshooting
  • Copilot Context Limits — catalog context metadata and prompt/output budgeting
  • Tool Choice Behavior — tool-choice and finish semantics across providers

Protocol and engineering reference

Historical design records:

Project

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, which includes the required offline gates, live-provider test boundaries, and a safe audit workflow for protocol investigations.

License

Router-Maestro is available under the MIT License.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for likanwen from gravatar.com likanwen

Credits

Author: Kanwen Li

License expression

MIT
View SPDX License List

Requires

Python >=3.14

Provides Extra

dev

Tags

api copilot llm load-balancing openai routing

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

router_maestro-0.9.0.tar.gz (943.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

router_maestro-0.9.0-py3-none-any.whl (473.2 kB view details)

Uploaded Python 3

File details

Details for the file router_maestro-0.9.0.tar.gz.

File metadata

  • Download URL: router_maestro-0.9.0.tar.gz
  • Upload date:
  • Size: 943.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for router_maestro-0.9.0.tar.gz
Algorithm Hash digest
SHA256 9301c8a28288ab86953593294e049f35484c11dfe43167302f830ae3e6b02a62
MD5 8e92c2ca32f6763a57fe84fd474803a6
BLAKE2b-256 699704638327ba489b32be53482ba6e02fa8955fa5b945fc75711fa4b2560411

See more details on using hashes here.

Provenance

The following attestation bundles were made for router_maestro-0.9.0.tar.gz:

Publisher: release.yml on MadSkittles/Router-Maestro

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file router_maestro-0.9.0-py3-none-any.whl.

File metadata

  • Download URL: router_maestro-0.9.0-py3-none-any.whl
  • Upload date:
  • Size: 473.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for router_maestro-0.9.0-py3-none-any.whl
Algorithm Hash digest
SHA256 2a8e8bb0cf4c95cb07436ebe42adef66e3d38a4d30694562ee0ecf44ec51efe6
MD5 96017fe84bf0c8312f37d87af8f766d8
BLAKE2b-256 54ae85e8e7208ccef44794dbe93359dd8a287404eea738d2ae81108a20d35e9b

See more details on using hashes here.

Provenance

The following attestation bundles were made for router_maestro-0.9.0-py3-none-any.whl:

Publisher: release.yml on MadSkittles/Router-Maestro

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.9.0 This release

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.10

2 files

0.7.9

2 files

0.7.8

2 files

0.7.7

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.28

2 files

0.3.27

2 files

0.3.26

2 files

0.3.25

2 files

0.3.24

2 files

0.3.23

2 files

0.3.22

2 files

0.3.21

2 files

0.3.20

2 files

0.3.19

2 files

0.3.18

2 files

0.3.17

2 files

0.3.16

2 files

0.3.15

2 files

0.3.14

2 files

0.3.13

2 files

0.3.12

2 files

0.3.11

2 files

0.3.10

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.0

2 files

0.1.37

2 files

0.1.36

2 files

0.1.35

2 files

0.1.34

2 files

0.1.33

2 files

0.1.32

2 files

0.1.31

2 files

0.1.30

2 files

0.1.29

2 files

0.1.28

2 files

0.1.27

2 files

0.1.26

2 files

0.1.25

2 files

0.1.24

2 files

0.1.23

2 files

0.1.22

2 files

0.1.21

2 files

0.1.20

2 files

0.1.19

2 files

0.1.18

2 files

0.1.17

2 files

0.1.16

2 files

0.1.15

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page