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, DeepSeek Harness, 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
DeepSeek Harness (DSH) OpenAI Responses Yes, with generated context and reasoning metadata
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 Chat Completions and native Responses
Anthropic API key Anthropic Messages
DeepSeek API key Native Messages, Chat, Responses, and Files; Gemini converts to Chat
Custom OpenAI-compatible API key, environment key, or explicit anonymous mode Chat Completions; optional native Responses

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

Providers own their catalog, authentication, endpoint bindings, and provider contracts. A shared transport policy defines default protocol preferences; compatibility paths and failure recovery are explicit opt-ins. Routing selects a model; the handler selects how to call it. Model fallback is independent of transport fallback and runs only after an eligible upstream failure. The Provider Plugins registry also mounts provider resource endpoints such as Files without hardcoding them in the application.

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
router-maestro config dsh

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. DSH configuration updates its Router-Maestro provider catalog in ~/.dsh/settings.yaml while preserving unrelated Harness settings.

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:
Newer release available (0.9.8)

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.7.tar.gz (1.0 MB 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.7-py3-none-any.whl (493.2 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: router_maestro-0.9.7.tar.gz
  • Upload date:
  • Size: 1.0 MB
  • 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.7.tar.gz
Algorithm Hash digest
SHA256 8ab8a32528aba5be169c2d16bf63ae3252bcaf3dd33bf3d5974f27be9f116e28
MD5 b106d04e489d8c26a9d55d6e9c3f24aa
BLAKE2b-256 b9afa8763e55dbaacb5c2f2611d17834d5ad14673a8e169f682a474a39866942

See more details on using hashes here.

Provenance

The following attestation bundles were made for router_maestro-0.9.7.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.7-py3-none-any.whl.

File metadata

  • Download URL: router_maestro-0.9.7-py3-none-any.whl
  • Upload date:
  • Size: 493.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.7-py3-none-any.whl
Algorithm Hash digest
SHA256 6ba90cf157e6cf9925151d9a38720269136631494535f4d74329d83c3b52c205
MD5 03ed27a5448670f37172ad470c47c322
BLAKE2b-256 bb77ad668e399edf7879ae935b7ab8c4948b1dd9167a9a0a42917a5e788eb853

See more details on using hashes here.

Provenance

The following attestation bundles were made for router_maestro-0.9.7-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

0.9.8

2 files

This release

0.9.7 This release

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

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