Comment exécuter votre propre routeur de modèles d'IA avec 9router

9router est un proxy de routage open source sous licence MIT qui s’exécute sur votre propre machine ou serveur. Il regroupe tous les fournisseurs d’IA que vous connectez derrière un unique endpoint compatible OpenAI, accessible à l’adresse http://localhost:20128/v1.

Si vous utilisez Claude Code dans un terminal, Cline dans votre éditeur et le SDK OpenAI dans un projet annexe, vous avez probablement trois jeux de clés et trois URL de base, et chaque outil exige sa propre modification de configuration dès que vous changez de modèle. 9router remplace tout cela par un seul endpoint local. Ce guide explique comment l’installer avec npm ou Docker, le vérifier avec curl, y connecter vos outils et le sécuriser avant de le rendre accessible au-delà de localhost.

Qu’est-ce que 9router ?

9router est un proxy auto-hébergé qui accepte des requêtes au format OpenAI, les achemine vers le fournisseur en amont que vous avez configuré et assure, si nécessaire, la conversion entre les formats de requête OpenAI, Claude et Gemini. Le README du projet recense plus de 40 fournisseurs pris en charge, et la CLI est distribuée sous la forme du package npm 9router.

La principale différence entre 9router et OpenRouter tient à l’endroit où s’exécute le routeur. OpenRouter est un service hébergé auquel vous envoyez vos requêtes. 9router est un logiciel que vous exécutez vous-même, et OpenRouter figure dans sa liste de fournisseurs : vous pouvez donc placer un compte OpenRouter derrière votre propre routeur.

Pourquoi exécuter un routeur de modèles auto-hébergé

Un routeur local fournit le même endpoint à tous vos outils et centralise les identifiants des fournisseurs. Vous pouvez ainsi changer de modèle sans toucher à la configuration des outils ni au code applicatif.

• Un seul endpoint. Tous les clients compatibles OpenAI utilisent la même URL de base.
• Des clés centralisées. Vous ajoutez les comptes fournisseurs une seule fois, dans le tableau de bord. Chaque outil n’a besoin que d’une clé API 9router.
• Changement de modèle par simple chaîne. Changer de modèle revient à modifier la valeur de model, rien de plus.
• Combos. Un combo est une liste ordonnée et nommée de modèles que vous utilisez comme nom de modèle. Lorsque le premier modèle a épuisé son quota, subit une limitation de débit (429) ou renvoie une erreur, le routeur essaie le suivant.

L’approche habituelle consiste à placer votre modèle préféré en premier, puis des modèles moins coûteux à sa suite. Pour comparer les prix par token avant de choisir vos modèles de repli, utilisez le calculateur de coûts d’API LLM.

Comment installer et exécuter 9router

9router s’installe comme CLI npm globale avec npm install -g 9router et se lance avec la commande 9router. Le serveur écoute sur le port 20128.

npm install -g 9router
9router
# Dashboard: http://localhost:20128
# API:       http://localhost:20128/v1

Si vous ne souhaitez pas d’installation globale, npx 9router permet de l’exécuter ponctuellement.

Pour l’exécuter dans Docker, utilisez l’image officielle decolua/9router, également publiée sous ghcr.io/decolua/9router :

docker run -d --name 9router \
  -p 20128:20128 \
  -v "$HOME/.9router:/app/data" \
  -e DATA_DIR=/app/data \
  -e INITIAL_PASSWORD='change-me' \
  decolua/9router:latest

Le montage de volume préserve la base de données SQLite (/app/data/db/data.sqlite dans le conteneur) lors des redémarrages du conteneur. Les nouvelles versions sont publiées fréquemment et le tag latest évolue avec elles : épinglez un tag de version précis si vous avez besoin de déploiements reproductibles.

Une fois 9router démarré, terminez la configuration dans le tableau de bord :

1. Ouvrez http://localhost:20128 et connectez-vous au tableau de bord.
2. Ajoutez au moins un compte fournisseur.
3. Créez une clé API pour vos outils.

Vérifier le routeur avec curl

Le moyen le plus rapide de vérifier que 9router fonctionne est d’envoyer une requête GET vers /v1/models, avant même de configurer le moindre outil. La réponse est une liste JSON de tous les modèles et combos que le routeur peut servir, au format de liste OpenAI standard.

curl http://localhost:20128/v1/models

La liste des modèles répond sans clé. Il en va autrement pour les requêtes de chat : le paramètre « Require API key » du tableau de bord est activé par défaut, elles nécessitent donc une clé générée dans le tableau de bord. Il est également judicieux d’envoyer la clé avec la requête de liste des modèles, car une clé restreinte à certains modèles ne voit que ceux-ci :

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer $NINE_ROUTER_API_KEY"

Si un identifiant de modèle de votre fournisseur apparaît dans la liste, le routage fonctionne. Si la liste est vide, le fournisseur n’est pas encore connecté.

Connecter vos outils à 9router

Tout client acceptant une URL de base OpenAI personnalisée peut utiliser 9router. Définissez l’URL de base sur http://localhost:20128/v1 et fournissez une clé API créée dans le tableau de bord.

SDK OpenAI

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:20128/v1",
  apiKey: process.env.NINE_ROUTER_API_KEY, // created in the 9router dashboard
});

const res = await client.chat.completions.create({
  model: "<an id or combo name from /v1/models>",
  messages: [{ role: "user", content: "Say hello" }],
});
console.log(res.choices[0].message.content);

Pour passer à un autre modèle ou à un combo, modifiez la chaîne model. Le reste du code demeure inchangé.

Agents de codage

Dans Cline, choisissez OpenAI Compatible comme fournisseur d’API et renseignez trois valeurs : l’URL de base http://localhost:20128/v1, votre clé API issue du tableau de bord et un identifiant de modèle copié depuis /v1/models. Les agents en terminal qui permettent d’utiliser votre propre fournisseur, comme OpenCode, acceptent ces trois mêmes valeurs.

Pi avec pi-9router-ext

L’extension pi-9router-ext connecte l’agent de codage Pi à 9router au moyen de deux variables d’environnement :

pi install npm:pi-9router-ext
NINE_ROUTER_BASE_URL=http://localhost:20128 NINE_ROUTER_API_KEY=<key> pi
# inside Pi:
/9router-models

Au démarrage, l’extension lit les modèles de chat depuis /v1/models. Dans la version 0.2.4, elle interroge également /v1/models/web pour découvrir les routes de recherche et de récupération web de 9router. Exécutez /9router-models dans Pi pour voir ce qu’elle a détecté.

Comment sécuriser 9router avant de l’exposer ?

Pour sécuriser 9router avant qu’une autre machine puisse y accéder, définissez un mot de passe pour le tableau de bord ainsi que les secrets JWT et de clé API, et laissez « Require API key » activé. Les valeurs par défaut conviennent sur localhost, mais pas au-delà. Si INITIAL_PASSWORD n’est pas défini, la première connexion au tableau de bord utilise 123456 tant qu’aucun mot de passe n’a été enregistré. Définissez ces valeurs à partir du fichier .env.example officiel avant d’ouvrir un port ou de déployer sur un hôte public :

INITIAL_PASSWORD=<long-random-string>   # first login otherwise uses 123456
JWT_SECRET=<long-random-string>         # listed under "Required" in .env.example
API_KEY_SECRET=<long-random-string>     # the example default is publicly known
AUTH_COOKIE_SECURE=true                 # set when serving behind an HTTPS reverse proxy

La vérification de la clé API est elle-même un paramètre du tableau de bord. Ouvrez la page Endpoint et assurez-vous que Require API key est activé, afin que les requêtes dépourvues de clé valide soient rejetées. Ce paramètre est activé par défaut, et le tableau de bord affiche un avertissement si l’endpoint est accessible depuis un hôte distant alors qu’il est désactivé.

Ne définissez AUTH_COOKIE_SECURE=true que si la terminaison TLS a lieu en amont de 9router. En HTTP simple, le navigateur ne renverra pas le cookie d’authentification.

Conclusion

Un routeur auto-hébergé comme 9router offre à tous vos outils un seul endpoint et un seul jeu d’identifiants, et changer de modèle revient simplement à modifier la chaîne model. Installez-le, vérifiez que /v1/models liste bien les modèles de votre fournisseur, puis connectez un premier outil à http://localhost:20128/v1. Définissez le mot de passe et les secrets, et laissez « Require API key » activé, avant que le routeur ne soit accessible au-delà de localhost.

FAQ

Comment exécuter 9router sur un autre port que 20128 ?

Lancez la CLI npm avec 9router --port 8080 pour utiliser un port personnalisé. Si vous l'exécutez depuis les sources, définissez la variable d'environnement PORT, ainsi que NEXT_PUBLIC_BASE_URL pointant vers le même port. Dans Docker, modifiez le côté hôte du mappage de ports, par exemple -p 8080:20128. Chaque outil doit alors utiliser la nouvelle URL de base, par exemple http://localhost:8080/v1.

Où 9router stocke-t-il sa configuration et ses données ?

9router stocke ses données dans le répertoire défini par DATA_DIR, qui vaut par défaut ~/.9router, et conserve sa base de données SQLite dans db/data.sqlite au sein de ce répertoire. Si JWT_SECRET n'est pas défini, un secret de signature généré automatiquement y est également stocké, dans ~/.9router/jwt-secret. L'image Docker officielle définit DATA_DIR sur /app/data : monter un volume sur /app/data permet donc de tout conserver.

Comment connecter les outils d'une autre machine à un serveur 9router distant ?

Exécutez npx 9router connect http://server-host:20128 sur la machine cliente. Cette commande ne démarre aucun serveur local. Elle se connecte avec le mot de passe du tableau de bord, réutilise ou crée une clé API nommée cli- suivi du nom d'hôte, puis écrit la configuration de chaque outil sélectionné. Elle sauvegarde une seule fois chaque configuration d'origine avec le suffixe .bak-9router. Utilisez --tools claude,codex pour choisir les outils à l'avance, et --reset pour annuler les modifications.

9router peut-il utiliser plusieurs comptes pour un même fournisseur ?

Oui. 9router prend en charge plusieurs comptes par fournisseur et répartit les requêtes entre eux selon un routage round-robin ou par priorité. Lorsqu'un compte atteint son quota, le routeur bascule vers le compte suivant. Ce mécanisme est distinct des combos : la rotation des comptes conserve le même modèle et change les identifiants utilisés, tandis qu'un combo bascule vers un autre modèle.