codexpi/docs/local-ai-pc-bridge.md

Bridge PC IA local pour CodexPi

Le bridge permet à CodexPi d’utiliser les modèles Ollama installés sur un PC du réseau privé. Ollama reste lié à 127.0.0.1:11434 : seul le bridge authentifié écoute sur le réseau local. Le jeton généré pendant l’association est enregistré dans les espaces privés de CodexPi et du PC ; il ne contient aucun mot de passe CodexPi.

Prérequis sur le PC

• Python 3.11 ou plus récent ;
• Ollama démarré ;
• au moins un modèle de conversation installé ;
• le PC et le Raspberry Pi joignables sur le même LAN ou tailnet privé.

Vérification rapide sous Windows :

ollama list
py --version

Association depuis la PWA

1. Ouvrez Réglages → Comptes IA.
2. Dans Serveur IA local sur PC, choisissez Ajouter un PC.
3. Téléchargez codexpi_ai_bridge.py et le fichier d’association codexpi-ai.codexpi-ai dans le même dossier.
4. Ouvrez PowerShell dans ce dossier puis lancez :

py .\codexpi_ai_bridge.py --pairing .\codexpi-ai.codexpi-ai

Sous macOS ou Linux :

python3 ./codexpi_ai_bridge.py --pairing ./codexpi-ai.codexpi-ai

Windows peut demander l’autorisation réseau pour Python. Autorisez uniquement les réseaux privés. Le port par défaut est 11435; Ollama lui-même n’est pas publié sur le LAN.

Après association, CodexPi détecte les modèles installés. Choisissez le modèle par défaut puis utilisez OpenCode · PC local lors de la création d’une discussion.

Redémarrage du bridge

L’association est conservée dans ~/.codexpi/ai-bridge.json. Aux démarrages suivants, la commande ne nécessite plus le fichier temporaire :

py .\codexpi_ai_bridge.py

Pour un démarrage automatique, créez un raccourci ou une tâche Windows qui exécute cette commande seulement après l’ouverture de session. Ne placez jamais le contenu de ~/.codexpi/ai-bridge.json dans Git ou dans un partage public.

Adresse ou port particuliers

Si le PC possède plusieurs interfaces réseau :

py .\codexpi_ai_bridge.py --pairing .\codexpi-ai.codexpi-ai `
  --advertise-address 192.168.1.20 --port 11435

Le bridge refuse d’annoncer une adresse Internet publique. Pour Tailscale, indiquez l’adresse privée du PC visible depuis le Pi.

Dépannage

• Ollama ne répond pas : ouvrez Ollama et vérifiez ollama list.
• Le Pi ne rejoint pas le bridge : vérifiez le pare-feu privé Windows et le port 11435, puis utilisez Tester la connexion dans CodexPi.
• Le modèle ne sait pas utiliser les outils : choisissez un modèle dont les capacités Ollama contiennent tools et prévoyez un contexte suffisant.
• Le PC est éteint : les comptes cloud restent disponibles ; les nouvelles tâches OpenCode locales échoueront proprement jusqu’au retour du bridge.

La révocation dans CodexPi efface sa copie chiffrée du jeton et retire le fournisseur OpenCode local. Arrêtez également le terminal du bridge sur le PC.