Installer pi coding agent en local et le brancher sur OpenRouter

À la fin de ce tutoriel, pi tourne dans votre terminal, relié à un modèle open-weight (Qwen3.6 35B A3B) via une clé OpenRouter, et vous savez le lancer en lecture seule ou dans un conteneur. Il s'adresse aux développeurs qui veulent un agent de code réduit à l'essentiel, qu'ils étendront eux-mêmes. En option, vous le brancherez sur un modèle servi localement par Ollama.

Pi se présente comme un « harness de code minimaliste » pour le terminal, sous licence MIT. Par défaut, il ne donne au modèle que quatre outils : read, write, edit et bash. Il n'intègre volontairement ni sous-agents, ni mode plan, ni MCP, ni fenêtres de permission : ces fonctions s'ajoutent par des extensions TypeScript, des skills ou des paquets. Lancé par Mario Zechner dans le dépôt badlogic/pi-mono, le projet a déménagé dans earendil-works/pi (l'ancienne adresse redirige vers la nouvelle), et le paquet npm a changé de nom. L'ancien paquet @mariozechner/pi-coding-agent est marqué comme obsolète sur npm, avec un renvoi vers @earendil-works/pi-coding-agent. Beaucoup de guides en ligne citent encore l'ancien nom.

Prérequis

• Node.js 22.19.0 ou plus récent, avec npm : c'est la version minimale déclarée par le paquet et vérifiée par le script d'installation.
• macOS ou Linux, ou Windows : pi y utilise par défaut Git Bash, que fournit Git for Windows. Un bash.exe présent dans le PATH (Cygwin, MSYS2, WSL) convient aussi.
• Un compte OpenRouter crédité.
• Git, pour le dépôt de test de la section 4 et pour revenir en arrière : pi n'annule pas lui-même les modifications de fichiers.

1. Installer pi

La méthode documentée par le README passe par npm :

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

L'option --ignore-scripts désactive les scripts d'installation des dépendances ; pi n'en a pas besoin. Le projet documente aussi un script, qui vérifie la version de Node.js et peut proposer de l'installer :

curl -fsSL https://pi.dev/install.sh | sh

Lisez-le avant de l'exécuter, comme tout script téléchargé. Si l'ancien paquet est installé, retirez-le d'abord, puisque les deux fournissent la commande pi :

npm uninstall -g @mariozechner/pi-coding-agent

Vérifiez l'installation :

pi --version

Plus tard, pi update --self met pi à jour.

2. Créer une clé OpenRouter et la brancher

Créer la clé

1. Créez un compte sur openrouter.ai et ajoutez du crédit depuis la page Credits.
2. Sur la page Keys, cliquez sur Create API Key, nommez la clé et fixez une limite de crédit, comme le recommande OpenRouter.
3. Copiez la clé.

Brancher la clé dans pi

Première méthode, la variable d'environnement documentée par pi pour OpenRouter :

export OPENROUTER_API_KEY="sk-or-v1-..."
pi --provider openrouter --model qwen/qwen3.6-35b-a3b

Deuxième méthode, la commande de connexion, dans pi :

/login openrouter

Deux choix s'offrent à vous. Sign in with OpenRouter ouvre une autorisation dans le navigateur, qui crée une clé facturée sur vos crédits OpenRouter ; cette clé n'expire pas d'elle-même. Use an API key enregistre la clé que vous avez créée. Dans les deux cas, elle est stockée dans ~/.pi/agent/auth.json, créé avec des droits limités à votre utilisateur (0600), et elle prime sur la variable d'environnement. Sur une machine distante (SSH), le navigateur ne peut pas joindre l'adresse de retour : collez alors dans pi l'URL de redirection finale.

Sur macOS, vous pouvez éviter de stocker la clé en clair : le champ key de auth.json accepte une commande, préfixée par !, dont la sortie devient la clé. Par exemple, pour une clé rangée dans le trousseau :

{
  "openrouter": { "type": "api_key", "key": "!security find-generic-password -ws 'openrouter'" }
}

Choisir le modèle

Qwen3.6 35B A3B est un modèle open-weight sous licence Apache 2.0, compatible avec l'appel d'outils selon le catalogue d'OpenRouter. Il figure dans le catalogue OpenRouter intégré à pi ; pi --list-models qwen3.6 le confirme. Dans une session, /model (ou Ctrl+L) ouvre le sélecteur, et Ctrl+S y enregistre le modèle sélectionné comme modèle de démarrage. Vous pouvez aussi l'écrire dans ~/.pi/agent/settings.json :

{
  "defaultProvider": "openrouter",
  "defaultModel": "qwen/qwen3.6-35b-a3b"
}

Si un modèle récent manque, pi update --models rafraîchit les catalogues.

3. (Option) Utiliser un modèle local

Pi accepte tout serveur compatible OpenAI (Ollama, LM Studio, vLLM) déclaré dans ~/.pi/agent/models.json. Avec Ollama, téléchargez le modèle (environ 23 Go selon sa page sur ollama.com) et démarrez le serveur avec une fenêtre de contexte d'au moins 64 000 tokens, le seuil que la documentation d'Ollama recommande pour les outils de code :

ollama pull qwen3.6:35b-a3b
OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Puis déclarez le fournisseur :

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "qwen3.6:35b-a3b", "contextWindow": 64000 }
      ]
    }
  }
}

Ollama ignore la clé, mais pi n'affiche un modèle dans /model que si une clé est définie : gardez cette valeur factice. Le champ contextWindow indique à pi la fenêtre réellement servie par Ollama ; sans lui, pi suppose 128 000 tokens. Lancez ensuite pi --provider ollama --model qwen3.6:35b-a3b. Le fichier est relu à chaque ouverture de /model, sans redémarrage.

La documentation d'Ollama propose aussi ollama launch pi, qui installe pi si nécessaire et le configure sur Ollama, en ajoutant un paquet de recherche web (@ollama/pi-web-search). Pi prend enfin en charge le serveur routeur de llama.cpp, via /login llama.cpp puis /llama.

4. Premier lancement

Créez un dépôt jetable avec un bug volontaire :

mkdir ~/essai-pi && cd ~/essai-pi
git init
printf 'def add(a, b):\n    return a - b\n\nprint(add(2, 3))\n' > calc.py
git add calc.py && git commit -m "État initial"

Commencez en lecture seule, en limitant les outils :

pi --tools read,grep,find,ls "Lis calc.py, explique ce que fait le script et identifie le bug. Ne modifie rien."

Relancez ensuite pi sans restriction et demandez la correction, puis, si Python 3 est installé, l'exécution de python3 calc.py pour vérifier que le script affiche 5.

Ce qu'il faut observer :

• l'en-tête de démarrage, qui liste les fichiers AGENTS.md ou CLAUDE.md chargés, les skills et les extensions ;
• les appels d'outils et leurs résultats (Ctrl+O replie ou déplie leur sortie) ;
• l'absence de toute demande de confirmation avant la commande : c'est le comportement normal de pi ;
• le pied de page, qui affiche le modèle, les tokens consommés, le coût et l'occupation du contexte.

Échap interrompt l'agent. Contrôlez le résultat avec git diff, et annulez si besoin avec git restore calc.py. La commande /tree navigue dans l'historique de la conversation, mais pi n'intègre pas de points de restauration des fichiers : son README range cette fonction parmi celles à ajouter par extension.

Sécurité et confidentialité

Aucune permission intégrée. Selon son README, pi ne restreint ni l'accès aux fichiers, ni les processus, ni le réseau, ni les identifiants : il s'exécute avec les droits de l'utilisateur qui le lance, et n'affiche aucune fenêtre d'approbation avant une commande. C'est un choix de conception, à compenser par l'isolement. Travaillez sur un dépôt de test, utilisez --tools read,grep,find,ls pour les phases d'analyse, et faites tourner pi dans un conteneur dès qu'il touche un vrai projet. La documentation de conteneurisation fournit ce Dockerfile.pi :

FROM node:24-bookworm-slim

RUN apt-get update \
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent

WORKDIR /workspace
ENTRYPOINT ["pi"]

Construisez l'image, puis lancez-la depuis le dossier du projet en transmettant la clé OpenRouter (les options placées après le nom de l'image sont passées à pi) :

docker build -t pi-sandbox -f Dockerfile.pi .
docker run --rm -it \
  -e OPENROUTER_API_KEY \
  -v "$PWD:/workspace" \
  -v pi-agent-home:/root/.pi/agent \
  pi-sandbox --provider openrouter --model qwen/qwen3.6-35b-a3b

L'agent ne voit alors, de votre disque, que le dossier monté, mais il y écrit directement, et la clé entre dans le conteneur. La même page décrit d'autres options, dont l'extension Gondolin (une micro-VM locale, les clés restant sur la machine hôte) et NVIDIA OpenShell (un bac à sable piloté par des règles).

Extensions et projets. Les paquets pi s'exécutent avec un accès complet au système : lisez leur code avant de les installer. Au démarrage, pi demande avant de faire confiance à un dossier qui contient des réglages ou des extensions propres au projet (.pi/) ; refusez pour un dépôt que vous ne connaissez pas.

Où vont les données. Avec OpenRouter, vos instructions, les fichiers lus et les sorties de commandes transitent par OpenRouter, puis par le fournisseur qui sert le modèle. OpenRouter ne conserve pas les prompts sauf activation explicite, mais garde des métadonnées. La conservation côté fournisseur varie : ses paramètres de confidentialité permettent de n'utiliser que des fournisseurs à conservation nulle. Avec Ollama, l'inférence reste sur la machine. Pi enregistre les sessions en JSONL dans ~/.pi/agent/sessions/. La commande /share publie la session en cours sous forme de gist GitHub privé, accompagné d'un lien de partage : toute personne qui a le lien peut la lire, à éviter donc sur du code sensible. Côté réseau, pi vérifie les mises à jour auprès de pi.dev à chaque démarrage, envoie un signal anonyme de version après la première installation et après chaque mise à jour, et ajoute des en-têtes d'attribution aux requêtes OpenRouter. PI_TELEMETRY=0 désactive le signal et les en-têtes ; PI_OFFLINE=1 supprime toutes les connexions réseau de démarrage, vérification de mise à jour comprise.

La clé. Jamais dans le dépôt : variable d'environnement, auth.json ou trousseau, avec une limite de crédit côté OpenRouter.

Dépannage

• Erreur de version de Node.js : pi exige Node.js 22.19.0 ou plus récent. Vérifiez avec node --version et mettez Node.js à jour.
• Modèle absent de /model : vérifiez que la clé du fournisseur est définie, puis lancez pi update --models pour rafraîchir les catalogues.
• Modèle local invisible : le fournisseur déclaré dans models.json doit avoir une valeur apiKey, même factice.
• Erreurs d'un serveur local compatible OpenAI : certains serveurs, dont Ollama et vLLM, ne comprennent pas le rôle developer. Ajoutez au fournisseur "compat": { "supportsDeveloperRole": false, "supportsReasoningEffort": false }.
• Windows : bash introuvable : installez Git for Windows, ou indiquez le chemin de votre bash avec shellPath dans ~/.pi/agent/settings.json.

Aller plus loin

• Comparer les harness et leurs philosophies : Claude Code vs Hermes vs Opencode : lequel choisir ?
• Installer les deux autres harness de cette série : OpenCode et Hermes Agent.
• Apprendre à cadrer, relire et sécuriser le travail d'un agent de code en équipe : formation Claude Code pour les équipes de développement.