Ce guide complet détaille l'installation de PI-Desktop, un client de bureau pour agent de codage IA axé sur le local. Il couvre la configuration sur macOS, Windows et Linux, permettant une mise en place fonctionnelle en environ 10 minutes. Le projet combine Electron pour l'interface, un cœur Rust pour la logique, un framework d'agent IA, et prend en charge des plugins installables par l'utilisateur.
Aperçu Rapide de PI-Desktop (30 secondes)
- Priorité au Local : Vos projets, sessions et identifiants restent sur votre machine. Les modèles peuvent être changés librement sans intermédiaire cloud obligatoire.
- Flexibilité des Modèles : Compatible avec OpenAI, Anthropic, toute API compatible OpenAI, ainsi qu'avec les passerelles locales comme Ollama et LM Studio.
- Migration Facile : Importez vos sessions existantes depuis Claude Code, Codex, OpenCode, ou Pi pour reprendre votre travail sans repartir de zéro.
- Extensibilité par Plugins : Personnalisez votre environnement de travail avec des plugins pour l'interface, les outils, le serveur MCP, et les thèmes.
- Vérification Préalable et Choix du Paquet d'Installation
La version actuelle est la 0.20.x (Aperçu Précoce). Consultez le tableau ci-dessous pour identifier le paquet adapté à votre système et suivez les instructions d'installation correspondantes.
| Système | Architecture | Paquet d'Installation | Mise à Jour |
|---|---|---|---|
| macOS | Apple Silicon (arm64) | .dmg / .zip |
Notification dans l'application pour télécharger les nouvelles versions |
| macOS | Intel (x64) | .dmg / .zip |
Notification dans l'application pour télécharger les nouvelles versions |
| Windows | x64 | Paquet d'installation NSIS / Archive ZIP portable | Téléchargement et installation via l'application (version NSIS) |
| Linux | x64 / ARM64 | .AppImage / .deb / .rpm / .asar |
Mise à jour via l'application (pour AppImage) |
Configuration Requise :
macOS et Windows n'ont pas de dépendances supplémentaires. Pour Linux, une seule exigence stricte s'applique : glibc version 2.35 ou supérieure. Cela correspond à Ubuntu 22.04+, Debian 12+, et Fedora 36+.
Les anciens systèmes (comme Ubuntu 20.04, Debian 11, Fedora 35) ne pourront pas exécuter le processus hôte Rust intégré, entraînant un échec au démarrage. Vérifiez votre version avec la commande :
ldd --version
Choix du Paquet :
Sur la page des Releases, repérez le nom du fichier correspondant à votre architecture. Pour macOS, choisissez -arm64 pour Apple Silicon ou -x64 pour Intel. Pour Linux, assurez-vous que l'architecture (x64 ou arm64) correspond à votre système. Choisir une architecture incorrecte empêchera l'application de démarrer.
Les détails sur les artefacts de build et les signatures sont disponibles dans docs/spec/06-delivery/06-release-runbook.md. Les versions officielles pour macOS sont signées par Developer ID et certifiées par Apple. Le paquet d'installation Windows ne nécessite pas de redistribuable VC++ supplémentaire. Les artefacts Linux sont construits sur Ubuntu 22.04 et vérifiés quant à la compatibilité glibc.
- Téléchargement, Installation et Vérification du Lancement
Chaque système nécessite une action clé pour l'installation et la vérification.
Installation sur macOS :
Ouvrez le fichier .dmg et faites glisser PI-Desktop.app dans le dossier /Applications. Lancez l'application. Les versions officielles sont signées et certifiées ; si vous rencontrez une erreur de "fichier endommagé", téléchargez à nouveau le paquet depuis une source officielle.
Installation sur Windows :
Deux options s'offrent à vous :
- Version avec installation (NSIS) : Exécutez
PI-Desktop-Setup-<version>.exepour suivre l'assistant d'installation. Vous pouvez choisir le répertoire d'installation. - Version portable (ZIP) : Extrayez l'archive
PI-Desktop-Portable-<version>.zipet lancez directementPI-Desktop.exe. Elle fonctionne sans nécessiter de droits administrateur et est idéale pour les supports amovibles ou les environnements restreints.
Le composant pi-desktop-host-core.exe est statiquement lié au MSVC CRT, ce qui permet une exécution directe sans nécessiter l'installation de runtimes supplémentaires. La version Windows 11 ARM peut exécuter l'application via la simulation x64.
Installation sur Linux :
Choisissez le format adapté à votre gestionnaire de paquets :
.AppImage: Le plus simple, double-cliquez pour exécuter. Recommandé en premier lieu..deb: Pour Ubuntu et Debian, utilisezapt install..rpm: Pour Fedora et les systèmes basés sur RHEL, utilisezdnf install. Le paquet sera installé dans/opt/PI-Desktop..asar: Pour les utilisateurs avancés, permet de reconditionner avec une installation Electron existante.
Si le fichier .AppImage ne peut être accédé lors de la première exécution, appliquez les permissions d'exécution :
chmod +x PI-Desktop-*.AppImage
./PI-Desktop-*.AppImage
Vérification du Lancement :
Sur tous les systèmes, l'application doit démarrer correctement et afficher une liste de tâches initiales dans le panneau de gauche. Cela confirme que l'installation a réussi et que l'interface est opérationnelle.
Les versions .deb, .rpm sous Linux et la version portable sous Windows utilisent un système de notification avec lien de téléchargement pour les mises à jour. Les autres formats (macOS .dmg, Windows NSIS, Linux .AppImage) bénéficient de mises à jour intégrées à l'application.
- Configuration Initiale
Après le premier lancement, une liste de tâches vous guidera. Vous pouvez aussi configurer manuellement les éléments suivants :
Ajout d'un Fournisseur de Modèle :
Allez dans Paramètres > Configuration des modèles. Sélectionnez votre fournisseur (cloud ou API compatible) et saisissez votre clé API ainsi que l'endpoint. La clé API sera stockée dans le trousseau système pour une sécurité accrue.
Ouverture d'un Projet :
Ajoutez un répertoire de projet local depuis la barre latérale. Les capacités d'outils locaux (lecture/écriture de fichiers, exécution de commandes) ne sont débloquées qu'après cette étape. Sans projet ouvert, l'agent ne pourra que discuter sans agir.
Sélection du Mode de Travail :
- Agent : Pour les modifications de code quotidiennes et l'exécution directe.
- Plan : Pour les refactorisations majeures, génère d'abord un plan avant exécution.
- Goal : Pour les tâches de longue haleine, définissez un objectif clair et des critères d'acceptation.
Les opérations sensibles nécessitent une autorisation explicite via la couche de permissions (Autoriser, Demander, Refuser).
Les utilisateurs venant de Claude Code, Codex, OpenCode ou Pi peuvent importer leurs sessions locales existantes pour conserver leur contexte.
- Réalisation de Votre Premier Script IA
Utilisez la barre de saisie pour interagir avec l'agent. Vous pouvez référencer des fichiers spécifiques avec @ et déclencher des commandes avec /. Émettez votre première instruction, par exemple : "Ajoute une suite de tests unitaires pour cette fonction."
Points de Vérification :
- Réponses en Flux Continu : L'agent doit afficher ses réponses de manière fluide et transparente, sans opacité.
- Gestion des Permissions : Les appels aux outils locaux doivent déclencher une demande d'autorisation avant exécution.
- Visualisation des Changements : Les modifications de code doivent être visibles sous forme de différences (diff), et les sorties des commandes doivent être consultables.
- Persistance de la Session : Fermez et rouvrez l'application ; l'historique de la session doit être entièrement restauré. La reprise inter-démarrages est une caractéristique fondamentale des sessions.
Si ces quatre points sont validés, votre installation, la connexion au modèle et la chaîne d'autorisations sont correctement configurées.
- Résolution Rapide des Problèmes Courants
| Symptôme | Cause Possible | Solution |
|---|---|---|
| L'application ne s'installe pas ou se ferme au lancement (Linux) | Version glibc inférieure à 2.35 | Vérifiez avec ldd --version et mettez à niveau vers Ubuntu 22.04+, Debian 12+, ou Fedora 36+. |
| macOS : L'appplication est signalée comme endommagée | Source de téléchargement non officielle | Retéléchargez le paquet signé depuis la page officielle des Releases. |
| Échec de connexion au modèle | Clé API ou Endpoint incorrect | Vérifiez et resauvegardez la clé API dans Configuration des modèles. Utilisez Tester le fournisseur avant de sauvegarder. |
| L'interface est normale, mais les outils ne fonctionnent pas | Aucun répertoire de projet ouvert | Ajoutez un dossier de projet via la barre latérale et réessayez. |
Pour le dépannage, consultez les fichiers journaux situés dans ~/.pi-desktop/logs/, organisés par app/, host/, et agent/ au format NDJSON. Des captures d'écran sont disponibles dans docs/guide/screenshots.md.
- Installation depuis les Sources (Optionnel)
Pour utiliser une version de développement ou contribuer au projet, assurez-vous d'avoir installé les outils suivants : Node.js (≥ 22.19), pnpm (≥ 10), et une chaîne d'outils Rust stable (la version minimale est spécifiée dans package.json à la racine).
git clone https://gitcode.com/GitHub_Trending/pid/PI-Desktop
cd PI-Desktop
pnpm install
cargo build -p host-core
pnpm build:js
pnpm dev
pnpm typecheck
pnpm test
pnpm dev lance l'application en suivant le même processus d'intégration que les versions officielles. Pour la construction de paquets finaux, référez-vous à docs/spec/06-delivery/06-release-runbook.md et aux commandes dist:\* spécifiques à chaque plateforme.
Conclusion
Avant de commencer, vérifiez votre version de glibc avec ldd --version (doit être ≥ 2.35) et sélectionnez le paquet d'installation approprié. Après le lancement, configurez votre modèle, ouvrez un répertoire de projet, soumettez votre première requête, et vérifiez les différences de code et les demandes d'autorisation. Pour une version de développement, utilisez Node.js ≥ 22.19, pnpm ≥ 10, et Rust pour exécuter pnpm dev. Suivez ces étapes pour rendre votre poste de travail IA local opérationnel.