Utilisez Pi avec votre propre modèle local

Pi est un agent de codage terminal open-source et BYOK (“bring your own key”) d’earendil-works. Il utilise le protocole de complétions de chat OpenAI et lit ses fournisseurs depuis un fichier de configuration JSON, vous permettant donc d’ajouter Tokios en tant que fournisseur personnalisé, de pointer baseUrl vers https://api.tokios.com/v1, et de piloter n’importe quel modèle derrière votre connecteur — sans que le port de ce modèle ne soit jamais exposé.

Prérequis

Un connecteur Tokios en cours d’exécution et apparié avec votre modèle local — voir Installation du connecteur
Un déploiement enregistré — voir Enregistrer un modèle
Une clé API Tokios (sk-tok-…) — voir Clés API
Pi installé — npm install -g @earendil-works/pi-coding-agent

Trouvez le nom de votre déploiement

Pi envoie le nom du déploiement — le nom public que vous avez enregistré dans le tableau de bord — et non l’ID de modèle amont utilisé par votre backend local. Les 2 sont souvent des chaînes différentes, et les confondre est la cause la plus fréquente d’un 404. Répertoriez les déploiements accessibles avec votre clé API :

curl https://api.tokios.com/v1/models \
  -H "Authorization: Bearer sk-tok-YOUR_KEY"

curl.exe https://api.tokios.com/v1/models `
  -H "Authorization: Bearer sk-tok-YOUR_KEY"

Chaque id présent dans la réponse est une valeur que vous pouvez utiliser dans models.json.

Exécutez ceci même si votre modèle répond déjà en Playground. Le Playground s’authentifie avec votre session de navigateur connectée, donc un test réussi sur cette interface ne prouve pas que votre clé sk-tok-… est valide ou limitée à ce déploiement. GET /v1/models est le premier appel qui teste la clé elle-même.

Où Pi conserve sa configuration

Pi lit les fichiers 2 depuis un répertoire .pi préfixé par un point dans votre dossier personnel :

Fichier	Objectif
`.pi/agent/models.json`	Fournisseurs, et les modèles servis par chaque fournisseur
`.pi/agent/settings.json`	Fournisseur et modèle par défaut

~/.pi/agent/models.json

C:\Users\<you>\.pi\agent\models.json

Créez le répertoire et le fichier s’ils n’existent pas encore.

Le répertoire est .pi, avec un point initial. Pi ne lit pas un fichier créé à l’emplacement pi/agent/models.json — il démarre normalement, et votre fournisseur n’apparaît simplement jamais dans /model.

Configurer un fournisseur personnalisé

Collez ceci dans models.json et remplacez les valeurs de remplacement 2. Il s’agit d’un fichier complet, et non d’un extrait. Le schéma de configuration de Pi peut évoluer entre les versions, donc confirmez les noms exacts des clés par rapport à votre version installée (voir pi.dev/docs).

~/.pi/agent/models.json

{
  "providers": {
    "tokios": {
      "baseUrl": "https://api.tokios.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-tok-YOUR_KEY",
      "models": [
        {
          "id": "gemma-tunnel",
          "input": ["text"]
        }
      ]
    }
  }
}

Un seul bloc provider peut servir tous les déploiements de votre compte. Ajoutez une entrée dans le tableau models pour chacun :

~/.pi/agent/models.json

{
  "providers": {
    "tokios": {
      "baseUrl": "https://api.tokios.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-tok-YOUR_KEY",
      "models": [
        { "id": "gemma-tunnel", "input": ["text"] },
        { "id": "qwen3-coder-tunnel", "input": ["text"] }
      ]
    }
  }
}

Remplacez gemma-tunnel par un nom de déploiement issu de GET /v1/models — pas l’ID de modèle amont que votre backend (Ollama, llama.cpp, vLLM ou LM Studio) sert, et pas la valeur Routes[].Model dans la configuration de votre connecteur, qui est l’ID amont. Remplacez sk-tok-YOUR_KEY par votre propre clé, et évitez de committer models.json avec une clé réelle dans le contrôle de version.

baseUrl doit inclure /v1, sans barre oblique finale. Le provider openai-completions de Pi construit les chemins de requête par rapport à cette URL, donc si https://api.tokios.com omet la surface API de Tokios, https://api.tokios.com/v1/ peut produire un séparateur en double.

Correspondre à la fenêtre de contexte (facultatif)

Pi dimensionne ses invites à partir de la fenêtre de contexte du modèle. Ollama, llama.cpp, LM Studio et vLLM servent chacun la longueur de contexte avec laquelle le modèle a été chargé, et non le maximum théorique du modèle, donc indiquez à Pi le nombre réel :

{ "id": "gemma-tunnel", "input": ["text"], "contextWindow": 32768 }

Le définir trop haut fait que Pi empaquette une invite que votre serveur local rejette — une erreur qui arrive via Tokios mais qui provient de votre propre machine. Les invites courtes masquent la discordance, donc elle apparaît généralement seulement lorsque Pi commence à envoyer des fichiers entiers. Confirmez le nom de la clé par rapport à votre version installée.

Le définir par défaut (facultatif)

Pour lancer Pi directement sur votre déploiement Tokios au lieu de le sélectionner à chaque session, définissez une valeur par défaut dans ~/.pi/agent/settings.json :

~/.pi/agent/settings.json

{
  "defaultProvider": "tokios",
  "defaultModel": "gemma-tunnel"
}

Sinon, choisissez le provider et le modèle à l’exécution avec la commande /model dans l’interface TUI de Pi.

Préférer la surface Anthropic ? (facultatif)

Pi prend également en charge le protocole de messages Anthropic. Pour router via la surface Anthropic de Tokios, définissez api sur anthropic-messages et supprimez le /v1 de baseUrl — les clients de style Anthropic utilisent la racine de base. Confirmez la valeur exacte de api que votre version de Pi attend.

"api": "anthropic-messages",
"baseUrl": "https://api.tokios.com"

Choisir un modèle capable d’outils

L’agent de Pi s’appuie sur l’appel d’outils pour lire des fichiers, exécuter des commandes et modifier du code. Tous les modèles locaux ne gèrent pas les appels d’outils de manière fiable — choisissez un déploiement soutenu par un modèle disposant d’un solide support d’appel d’outils avant de vous fier à Pi pour des modifications réelles. Consultez Choisir un modèle par tâche pour obtenir des conseils sur l’adéquation d’un modèle aux travaux de codage agentique.

Dépannage

Tokios n'apparaît pas dans /model

Pi ne lit pas votre fichier. Confirmez qu’il se trouve à ~/.pi/agent/models.json — le répertoire est .pi, avec un point initial, et sous Windows cela se résout en C:\Users\<you>\.pi\agent\models.json. Confirmez également que le fichier est un JSON valide, avec providers comme objet indexé par le nom du fournisseur et models comme un tableau.

401 erreur

La clé API envoyée par Pi est manquante, mal formée ou a été révoquée. Confirmez que apiKey contient la clé sk-tok-… complète sans espaces superflus, et vérifiez son statut sur l’onglet Keys. Une session Playground fonctionnelle ne l’exclut pas — le Playground n’utilise pas votre clé API.

404 erreur

Le modèle id sous models ne correspond pas à un déploiement enregistré. Exécutez GET /v1/models et copiez un id de la réponse exactement. Un écart courant consiste à utiliser l’ID de modèle amont de votre connecteur Routes[].Model au lieu du nom du déploiement.

403 erreur

La clé existe mais n’est pas limitée au déploiement que vous avez configuré, ou votre compte est suspendu. Vérifiez les modèles de la clé sur l’onglet Keys.

503 erreur

Le connecteur pour ce déploiement est hors ligne ou atteint sa limite de concurrence. Vérifiez l’onglet Connectors — le connecteur doit apparaître comme Online, et la machine qui l’exécute doit être toujours active et accessible.

Les longues sessions échouent, les courtes fonctionnent

Pi envoie plus de contexte que votre backend n’en a chargé. Définissez contextWindow sur l’entrée du modèle à la longueur de contexte que votre serveur sert réellement, et confirmez le paramètre au moment du chargement dans Ollama, llama.cpp, LM Studio ou vLLM.

Prochaines étapes

omp (oh-my-pi)

Vous préférez la fourche batteries-included ? Configurez omp contre Tokios de la même manière.

Choisissez un modèle par tâche

Associez un modèle local au travail de codage agentique avant de l’engager sur Pi.

Matériel et compatibilité

Servir et connecter votre runtime

Connecter un client ou une app

Comparer

Utilisez Pi avec votre propre modèle local

Prérequis

Trouvez le nom de votre déploiement

Où Pi conserve sa configuration

Configurer un fournisseur personnalisé

Correspondre à la fenêtre de contexte (facultatif)

Le définir par défaut (facultatif)

Préférer la surface Anthropic ? (facultatif)

Choisir un modèle capable d’outils

Dépannage

Prochaines étapes

omp (oh-my-pi)

Choisissez un modèle par tâche

​Prérequis

​Trouvez le nom de votre déploiement

​Où Pi conserve sa configuration

​Configurer un fournisseur personnalisé

​Correspondre à la fenêtre de contexte (facultatif)

​Le définir par défaut (facultatif)

​Préférer la surface Anthropic ? (facultatif)

​Choisir un modèle capable d’outils

​Dépannage

​Prochaines étapes

omp (oh-my-pi)

Choisissez un modèle par tâche

Prérequis

Trouvez le nom de votre déploiement

Où Pi conserve sa configuration

Configurer un fournisseur personnalisé

Correspondre à la fenêtre de contexte (facultatif)

Le définir par défaut (facultatif)

Préférer la surface Anthropic ? (facultatif)

Choisir un modèle capable d’outils

Dépannage

Prochaines étapes