Installer OmniRoute sur un VPS Linux avec Docker : passerelle IA auto-hébergée

Quand on utilise plusieurs fournisseurs d'IA (OpenAI, Anthropic, Mistral, un modèle Ollama local), chaque service a sa propre API, ses propres clés, son propre format de requête. OmniRoute est une passerelle IA open source (licence MIT) qui place un endpoint unique compatible OpenAI devant plus de 380 fournisseurs et plus de 1 400 identifiants de modèles. Routage intelligent, fallback automatique entre providers, équilibrage de charge, cache de réponses et chiffrement des clés API : tout passe par un seul point d'entrée auto-hébergé sur votre VPS Linux.

Ce guide détaille l'installation d'OmniRoute avec Docker sur un VPS Linux, la configuration des providers (OpenAI, Anthropic, Ollama local), la sécurisation de l'accès par token et le branchement d'outils comme Claude Code ou Cursor sur votre passerelle. Il complète nos guides installer Ollama sur VPS Linux et installer Open WebUI avec Docker pour les administrateurs qui veulent centraliser l'accès à plusieurs fournisseurs d'IA depuis un seul serveur.

Pourquoi auto-héberger une passerelle IA sur un VPS

Appeler directement l'API d'OpenAI, d'Anthropic ou de Mistral depuis chaque outil (IDE, script, agent) pose plusieurs problèmes concrets pour un administrateur de serveur :

• Clés API dispersées : chaque outil stocke sa propre clé. Une fuite sur un poste expose toutes les clés configurées.
• Pas de fallback : si l'API d'un fournisseur est en panne, l'outil s'arrête. Aucune bascule automatique vers un autre modèle.
• Pas de visibilité : impossible de savoir quel outil consomme combien de tokens, ni de fixer un budget global.
• Formats incompatibles : l'API d'Anthropic n'a pas le même format que celle d'OpenAI. Changer de fournisseur impose de modifier le code de chaque client.

Une passerelle IA comme OmniRoute résout ces quatre problèmes en centralisant les clés, le routage et le monitoring sur un seul VPS. Tous les clients se connectent à http://votre-vps:20128/v1 avec une seule clé OmniRoute, et la passerelle traduit les requêtes vers le bon fournisseur.

Prérequis

• Un VPS Linux sous Ubuntu 22.04 LTS, Ubuntu 24.04 LTS ou Debian 12 avec au moins 2 vCPU, 2 Go de RAM et 25 Go de SSD ;
• Docker Engine 24+ installé (guide d'installation de Docker sur VPS) ;
• Un accès SSH avec un utilisateur disposant des droits sudo ;
• Au moins une clé API d'un fournisseur d'IA (OpenAI, Anthropic, Mistral, DeepSeek) ou un serveur Ollama local.

Installer OmniRoute avec Docker

OmniRoute est distribué sous forme d'image Docker multi-architecture (AMD64 et ARM64). L'installation minimale tient en une seule commande :

docker run -d --name omniroute --restart unless-stopped \
  --stop-timeout 40 \
  -p 127.0.0.1:20128:20128 \
  -v omniroute-data:/app/data \
  diegosouzapw/omniroute:latest

Cette commande démarre OmniRoute sur le port 20128, en écoute uniquement sur 127.0.0.1 (localhost). Les données persistantes (configuration, base SQLite, clés chiffrées) sont stockées dans le volume Docker omniroute-data.

Pour vérifier que le conteneur tourne :

docker logs omniroute --tail 20

Le message listening on port 20128 confirme que la passerelle est prête.

Déploiement avec Docker Compose

Pour un déploiement plus structuré avec Redis (cache et rate limiting), créez un répertoire dédié et un fichier de configuration (voir notre guide Docker Compose) :

mkdir -p /opt/omniroute && cd /opt/omniroute

Générez les secrets nécessaires :

openssl rand -hex 32 > jwt_secret.txt
openssl rand -hex 32 > api_key_secret.txt
openssl rand -hex 32 > storage_key.txt

Créez le fichier .env :

JWT_SECRET=$(cat jwt_secret.txt)
API_KEY_SECRET=$(cat api_key_secret.txt)
STORAGE_ENCRYPTION_KEY=$(cat storage_key.txt)
INITIAL_PASSWORD=VotreMotDePasseAdmin
NODE_ENV=production
REQUIRE_API_KEY=true
APP_BIND_HOST=127.0.0.1

Créez le fichier docker-compose.yml :

services:
  omniroute:
    image: diegosouzapw/omniroute:latest
    container_name: omniroute
    restart: unless-stopped
    stop_grace_period: 40s
    env_file: .env
    ports:
      - "127.0.0.1:20128:20128"
    volumes:
      - omniroute-data:/app/data
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:7-alpine
    container_name: omniroute-redis
    restart: unless-stopped
    volumes:
      - omniroute-redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3

volumes:
  omniroute-data:
  omniroute-redis-data:

Démarrez la stack :

docker compose up -d

Configurer les providers IA

Ouvrez le tableau de bord OmniRoute dans votre navigateur : http://127.0.0.1:20128 (ou via un tunnel SSH si vous accédez depuis votre poste local). Connectez-vous avec le mot de passe défini dans INITIAL_PASSWORD.

Depuis le tableau de bord, ajoutez vos fournisseurs d'IA. Chaque provider nécessite sa clé API, qu'OmniRoute chiffre en AES-256-GCM avant de la stocker sur le disque.

OpenAI

Ajoutez votre clé API OpenAI depuis le tableau de bord. Tous les modèles GPT (GPT-4o, GPT-4.1, o3) deviennent accessibles via l'endpoint /v1/chat/completions d'OmniRoute.

Anthropic (Claude)

Ajoutez votre clé API Anthropic. OmniRoute traduit automatiquement les requêtes au format OpenAI vers le format natif d'Anthropic : pas besoin de modifier vos clients.

Ollama (modèles locaux)

Si vous avez Ollama installé sur le même VPS, ajoutez-le comme provider avec l'URL http://host.docker.internal:11434 (ou http://172.17.0.1:11434 si host.docker.internal n'est pas résolu). Vos modèles locaux (Llama, Mistral, Qwen) apparaissent alors dans la liste des modèles disponibles d'OmniRoute, sans clé API.

Routage intelligent et fallback

OmniRoute propose 20 stratégies de routage. Les plus utiles pour un administrateur :

Le fallback en 4 niveaux (abonnement, clé API payante, tier économique, tier gratuit) garantit qu'une requête aboutit même si le provider principal est en panne ou a dépassé son quota. Le circuit breaker intégré détecte les erreurs répétées sur un provider et le met temporairement hors circuit avec un backoff exponentiel, pour éviter de gaspiller des requêtes vers un service défaillant.

Pour envoyer une requête avec routage automatique, utilisez "model": "auto" dans votre appel API :

curl http://127.0.0.1:20128/v1/chat/completions \
  -H "Authorization: Bearer VOTRE_CLE_OMNIROUTE" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Bonjour"}]
  }'

Sécuriser l'accès par token

En production, trois mesures sont indispensables :

1. Activer l'authentification par clé API : la variable REQUIRE_API_KEY=true dans le fichier .env refuse toute requête sans header Authorization: Bearer. Générez une clé depuis le tableau de bord OmniRoute et distribuez-la uniquement aux outils autorisés.
2. Écouter sur localhost uniquement : le paramètre APP_BIND_HOST=127.0.0.1 empêche tout accès direct depuis Internet. L'accès distant passe par un reverse proxy Nginx avec TLS ou un tunnel SSH.
3. Protéger le serveur : durcissez l'accès SSH, configurez Fail2ban et n'ouvrez dans le pare-feu que les ports 22, 80 et 443.

Le chiffrement AES-256-GCM des clés API stockées signifie que même un accès en lecture au volume Docker ne permet pas de récupérer les clés en clair. Cependant, un accès root au conteneur en cours d'exécution permet de lire la mémoire vive du processus : limitez les accès root et utilisez un utilisateur non-root pour l'administration courante.

Connecter Claude Code ou Cursor

Claude Code, Cursor, Continue et tout outil compatible avec l'API OpenAI peuvent se connecter à OmniRoute en pointant vers votre endpoint local :

Claude Code

Configurez la variable d'environnement pour rediriger les appels API vers votre passerelle :

export ANTHROPIC_BASE_URL=http://127.0.0.1:20128/v1
export ANTHROPIC_API_KEY=votre-cle-omniroute

Cursor

Dans les paramètres de Cursor, section Models, ajoutez un endpoint personnalisé :

• Base URL : http://127.0.0.1:20128/v1
• API Key : votre clé OmniRoute

Cursor envoie alors ses requêtes à OmniRoute, qui les route vers le bon provider selon la stratégie configurée.

Accès distant via tunnel SSH

Si OmniRoute écoute sur localhost et que vous travaillez depuis un autre poste, ouvrez un tunnel SSH :

ssh -L 20128:127.0.0.1:20128 utilisateur@votre-vps

Vos outils locaux se connectent alors à http://127.0.0.1:20128/v1 comme si OmniRoute tournait sur votre machine.

Comparaison : appels directs vs. passerelle OmniRoute

Mise à jour et sauvegarde

Pour mettre à jour OmniRoute vers la dernière version :

cd /opt/omniroute
docker compose pull
docker compose up -d

Les données persistent dans les volumes Docker. Pour sauvegarder le volume de données :

docker run --rm -v omniroute-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/omniroute-data-$(date +%F).tar.gz /data

Résolution de problèmes courants

• Le conteneur redémarre en boucle : vérifiez les logs avec docker logs omniroute --tail 50. Cause fréquente : un secret manquant dans le fichier .env ou un port déjà occupé.
• Erreur 401 sur les requêtes : REQUIRE_API_KEY=true est actif et le header Authorization: Bearer est absent ou contient une clé invalide. Générez une nouvelle clé depuis le tableau de bord.
• Ollama non détecté : vérifiez que le service Ollama écoute sur 0.0.0.0:11434 (et non 127.0.0.1) pour être accessible depuis le conteneur Docker. Testez avec curl http://172.17.0.1:11434/api/tags depuis le conteneur.
• Réponses lentes : augmentez la mémoire allouée avec OMNIROUTE_MEMORY_MB=2048 dans le fichier .env. La valeur par défaut (1 024 Mo) suffit pour le tableau de bord, mais les agents de code nécessitent davantage de mémoire vive.

Aller plus loin

• Installez Open WebUI et pointez-le vers OmniRoute pour disposer d'une interface de chat web unifiée devant tous vos modèles.
• Comparez les moteurs d'inférence locale avec notre guide vLLM vs Ollama sur serveur dédié pour choisir le backend local le plus adapté à votre charge.
• Placez OmniRoute derrière un reverse proxy Nginx avec un certificat TLS pour exposer la passerelle en HTTPS sur un nom de domaine dédié.

Conclusion

OmniRoute transforme un VPS Linux en passerelle IA centralisée : un seul endpoint, un seul jeu de clés, un routage intelligent avec fallback automatique. Les clés des fournisseurs restent chiffrées sur votre serveur au lieu d'être dispersées dans chaque outil. L'installation avec Docker se fait en quelques minutes et la configuration des providers passe par un tableau de bord web. Pour les administrateurs qui utilisent déjà Ollama en local, OmniRoute permet de mélanger modèles locaux et API cloud derrière une interface unifiée.