Installer OpenCode sur un VPS avec tmux

Ce qu’est OpenCode et ce que vous allez configurer

OpenCode est un agent de codage IA open source conçu pour le terminal. Vous le lancez dans le répertoire d’un projet. Il lit votre code, propose des modifications, édite des fichiers et exécute des commandes, le tout depuis une interface utilisateur de terminal (TUI). Il est distribué sous licence MIT et se connecte à plus de 75 fournisseurs de modèles. Avec environ 213,000 étoiles GitHub en octobre 2026, c’est l’agent de codage open source qui en compte le plus. Pour exécuter OpenCode sur un VPS, vous l’installez sous un utilisateur dédié sans privilèges, vous placez la clé API du modèle dans un fichier privé, puis vous le lancez dans tmux afin que la session soit conservée en cas de coupure de votre connexion. Ce guide suit exactement cet ordre.

Une précision sur les noms évite toute confusion. Le dépôt canonique est anomalyco/opencode, maintenu par l’équipe Anomaly (auparavant connue sous le nom SST), et le projet se trouvait auparavant à l’adresse sst/opencode. Un ancien dépôt sans lien, nommé opencode-ai/opencode et désormais archivé, existe également sur GitHub. Vérifiez donc que vous consultez la documentation du bon projet. Le site officiel est opencode.ai.

Pourquoi exécuter OpenCode sur un VPS

Une session avec un agent de programmation est longue. OpenCode peut passer plusieurs minutes à effectuer une refactorisation ou à exécuter une suite de tests. S’il s’exécute sur votre ordinateur portable, la fermeture du capot ou une coupure du Wi-Fi interrompt la session en cours. Sur un VPS, à l’intérieur de tmux, l’agent continue de travailler après votre déconnexion. Vous pouvez ensuite vous reconnecter à la session pour consulter son travail. C’est le même principe que pour exécuter Claude Code sur un VPS avec tmux. C’est le principal avantage pratique du déplacement d’un agent hors de votre ordinateur portable.

La deuxième raison tient à l’emplacement. Un VPS est proche du code que vous déployez : le dépôt, les outils de build, la base de données de test et, souvent, l’environnement de staging se trouvent déjà sur cette machine ou à proximité. Un agent qui modifie le code et exécute les tests fonctionne mieux sur la machine où ces tests s’exécutent réellement. Comme cette machine est un serveur que vous contrôlez, vous pouvez aussi fournir volontairement à l’agent un environnement isolé, comme décrit dans la section suivante.

Si vous choisissez encore un outil, exécuter un agent de programmation basé sur l’IA sur un VPS compare les principales solutions, notamment Aider et Goose.

Donner son propre utilisateur à OpenCode

Voici le point de départ : un agent de programmation modifie des fichiers et exécute des commandes. C’est son rôle, et c’est aussi le risque. OpenCode exécute les builds, les tests et les commandes shell nécessaires à la tâche. Le jugement du modèle est bon, mais pas parfait. Le compte utilisé par l’agent limite ce qu’une commande dangereuse peut atteindre. N’exécutez donc pas OpenCode en tant que root et n’utilisez pas le même utilisateur que celui qui administre le serveur.

Contrairement à un agent d’arrière-plan, OpenCode est interactif. Son utilisateur doit donc disposer d’un shell réel et d’un répertoire personnel :

sudo useradd --create-home --shell /bin/bash opencode
sudo -iu opencode

Conservez les projets sur lesquels il doit travailler sous /home/opencode et clonez-les avec cet utilisateur. N’accordez aucun droit sudo à ce compte. Si l’agent exécute une commande destructive, il ne peut détruire que ce que ce compte possède. Le raisonnement est le même que pour exécuter les services avec un utilisateur non privilégié. Travaillez également dans un dépôt git et faites un commit avant de confier une tâche à l’agent. En cas de modification incorrecte, vous pourrez alors revenir en arrière avec git revert ou git restore, au lieu de perdre le travail. Les modifications qui n’ont jamais été validées ne sont pas protégées.

Installer OpenCode

La documentation du projet décrit plusieurs méthodes d’installation, dont deux conviennent à un serveur. Le script d’installation est la méthode la plus rapide. L’exécuter avec l’utilisateur opencode conserve tous les fichiers dans le répertoire personnel de cet utilisateur :

curl -fsSL https://opencode.ai/install | bash

La règle habituelle concernant curl | bash s’applique ici comme ailleurs : sur un serveur important, téléchargez d’abord le script, lisez-le, puis exécutez-le. Après l’installation, ouvrez un nouveau shell pour que la modification du PATH effectuée par l’installeur soit prise en compte. Vérifiez ensuite que le binaire répond :

opencode --version

Si vous préférez un gestionnaire de paquets et que Node.js est déjà installé sur le serveur, la méthode npm installe le même outil dans le préfixe global de npm :

sudo npm install -g opencode-ai

Avec un Node.js installé à l’échelle du système, ce préfixe est généralement /usr/local ou /usr. Leur répertoire bin figure dans le PATH de tous les utilisateurs. Un gestionnaire de versions ou un préfixe personnalisé place le binaire ailleurs. Exécutez donc d’abord npm prefix -g si vous devez faire trouver opencode à l’utilisateur opencode.

Dans les deux cas, la vérification est identique : opencode --version affiche un numéro de version. Un command not found après l’installation avec le script signifie que le shell actuel n’a pas encore relu le PATH mis à jour. Déconnectez-vous, puis reconnectez-vous avec l’utilisateur opencode.

Les deux commandes installent la branche OpenCode 1.x, qui publie toujours des versions (1.19.0 le 11 octobre 2026), et ce guide décrit cette branche. OpenCode 2 est désormais disponible avec une installation distincte, depuis https://opencode.ai/v2/install ou le paquet npm @opencode/cli, et son fonctionnement est différent : un serveur d’arrière-plan partagé par compte utilisateur gère les sessions, les permissions et l’exécution des outils, tandis que le terminal s’y connecte. Son guide de migration indique de supprimer une installation 1.x gérée par un paquet avant d’installer la version 2, car les deux utilisent la commande opencode.

Placer la clé API dans un fichier privé

OpenCode a besoin d’une clé pour le fournisseur de modèles que vous utilisez. Cette clé peut engager des dépenses à votre charge. Traitez-la donc comme un mot de passe. Créez un fichier que seul l’utilisateur opencode peut lire, avec le mode 600. Conservez-y la clé au lieu de la saisir dans des commandes, où elle apparaîtrait dans l’historique de votre shell :

install -m 600 /dev/null ~/opencode.env
nano ~/opencode.env

Ajoutez-y la variable de votre fournisseur, par exemple ANTHROPIC_API_KEY=... ou son équivalent pour votre fournisseur. OpenCode utilise les variables d’environnement standard des fournisseurs. Chargez le fichier dans votre shell avant de démarrer l’agent :

set -a; source ~/opencode.env; set +a

OpenCode propose aussi une méthode interactive. La commande /connect dans la TUI vous guide pour ajouter un fournisseur et enregistre l’identifiant dans ~/.local/share/opencode/auth.json dans le répertoire personnel de l’utilisateur. Si vous utilisez cette méthode, vérifiez que le fichier est privé avec chmod 600 ~/.local/share/opencode/auth.json. Les deux méthodes empêchent la clé d’apparaître dans vos lignes de commande. Choisissez-en une et utilisez-la systématiquement.

Démarrer OpenCode dans tmux

tmux rend l’installation sur un VPS vraiment utile, car une session tmux continue de fonctionner lorsque votre connexion SSH se termine. Démarrez une session, accédez à votre projet, puis lancez l’agent :

tmux new -s opencode
cd ~/my-project
opencode

Vous devriez voir la TUI s’ouvrir, avec une invite en bas et le nom de votre projet dans l’interface. Donnez-lui une tâche en langage courant. Il commence alors à lire les fichiers et à proposer des modifications. Pour quitter, détachez-vous avec Ctrl-b puis d. L’agent continue de fonctionner même si vous fermez votre ordinateur portable. Reconnectez-vous plus tard avec :

tmux attach -t opencode

La session, la conversation et toute tâche en cours se trouvent exactement là où vous les avez laissées. Cela résiste aux déconnexions, mais pas au redémarrage du serveur. Après un redémarrage, démarrez une nouvelle session tmux de la même manière. Rien ne vous empêche d’ouvrir une deuxième fenêtre tmux et d’exécuter un autre agent à côté du premier. Toutefois, les sessions OpenCode restent indépendantes les unes des autres, tandis que les sessions Claude Code sur le même serveur peuvent s’envoyer des messages, ce qui constitue une autre manière de répartir une tâche en deux.

Le relier à un modèle

OpenCode est indépendant du fournisseur. Il utilise l’AI SDK et le catalogue Models.dev pour prendre en charge plus de 75 fournisseurs. Le même outil fonctionne donc avec Anthropic, OpenAI, Google et des dizaines d’autres, y compris des serveurs locaux. La méthode la plus rapide consiste à utiliser la commande /connect dans la TUI. Elle liste les fournisseurs et gère les identifiants d’authentification. Pour obtenir une configuration que vous pouvez versionner et reproduire, créez un fichier opencode.json à la racine du projet et définissez le modèle avec provider/model-id :

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-5-5"
}

Choisissez un modèle encore proposé par votre fournisseur. Anthropic a retiré claude-sonnet-4-20250514 le 15 June 2026. Les configurations qui le référencent encore échouent.

Un modèle local fonctionne avec le même fichier, car n’importe quel serveur compatible avec l’API OpenAI peut être déclaré comme fournisseur. Si vous servez un modèle avec Ollama sur le même VPS, la configuration pointe vers son API locale. Le nom du modèle correspond alors à celui affiché par ollama list sur votre machine :

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": { "your-model-name": { "name": "Local coding model" } }
    }
  }
}

Adoptez dès le premier jour une habitude intégrée utile. OpenCode fournit deux agents, entre lesquels vous basculez avec la touche Tab : Build, l’agent par défaut avec un accès complet, et Plan, un agent restreint destiné à l’analyse, qui bloque les modifications de fichiers ou demande une confirmation. Plan n’est toutefois pas strictement en lecture seule. Il peut encore exécuter des commandes shell, et une commande shell peut modifier des fichiers. Commencez une nouvelle tâche dans Plan. Laissez-le lire le code et proposer une méthode. Passez à Build uniquement lorsque vous approuvez le plan. Si vous voulez que cette première passe soit réellement en lecture seule, interdisez les modifications et les commandes shell pour Plan dans opencode.json. OpenCode considère deny comme un blocage de l’action, tandis que ask vous demande seulement votre approbation :

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": { "edit": "deny", "bash": "deny" }
    }
  }
}

Sur un serveur, une première passe qui ne peut rien modifier constitue une précaution peu coûteuse. Claude Code présente le même choix sous la forme de modes d’autorisation plutôt que d’agents. Son passage au mode automatique par défaut mérite d’être lu si vous utilisez les deux outils, car le mode dans lequel une session démarre détermine l’ampleur des modifications qu’un agent non surveillé peut effectuer.

Le périmètre des dégâts, concrètement

Un agent de programmation n’est pas passif. Il faut donc préciser ce que cette configuration contient et ce qu’elle ne contient pas. Elle limite les dégâts sur les fichiers : l’utilisateur opencode possède son propre répertoire personnel et rien d’autre. Les modifications et les suppressions s’arrêtent donc à cette limite. Elle limite aussi l’exposition des identifiants : la clé se trouve dans un seul fichier en mode 600, dans un seul compte. En revanche, elle ne limite pas ce que le compte peut légitimement faire. Si le répertoire du projet contient des identifiants de déploiement en production, l’agent peut les utiliser. Gardez-les entièrement hors du compte de l’agent.

Contrairement à un agent passerelle comme OpenClaw, OpenCode 1.x est un programme interactif exécuté dans le terminal, pas un daemon. Par défaut, il n’ouvre aucun port en écoute. Seuls les indicateurs --port, --hostname ou --mdns permettent au TUI d’écouter. Il n’exécute aucun service permanent. Il n’y a donc pas d’unité systemd à créer ni de port à filtrer pour l’agent lui-même. OpenCode 2 modifie ce fonctionnement avec son serveur d’arrière-plan partagé. Vérifiez donc de nouveau ce point avant la migration. Le cloisonnement repose sur le compte utilisateur et le répertoire du projet. C’est pourquoi la première section de ce guide est la plus importante.

Le serveur qui l’héberge doit malgré tout recevoir les mesures habituelles, car un VPS de développement reste un serveur public : SSH avec authentification par clé uniquement et connexion root désactivée, comme dans Renforcer la sécurité SSH sur un VPS, pare-feu en refus par défaut et mises à jour régulières. Examinez aussi ce que l’agent produit. Lisez ses diffs avant de les pousser, comme vous liriez une pull request d’un nouveau contributeur, car c’est vous qui déployez le résultat.

Enfin, gardez l’outil lui-même à jour. OpenCode publie souvent de nouvelles versions, qui corrigent des problèmes importants pour un programme exécutant des commandes sur votre serveur. La mise à jour suit la même méthode que l’installation : relancez le script d’installation en tant qu’utilisateur opencode, ou exécutez sudo npm update -g opencode-ai si vous l’avez installé avec npm, puis vérifiez la nouvelle version avec opencode --version. Les deux méthodes vous maintiennent sur la branche 1.x. Le passage à OpenCode 2 est une migration distincte. Quelques minutes de maintenance de temps à autre coûtent moins cher que le débogage d’un comportement déjà corrigé depuis plusieurs mois.

FAQ

OpenCode peut-il utiliser un modèle local au lieu d’une API payante ?

Oui. OpenCode considère tout serveur compatible avec l’API OpenAI comme un provider. Un modèle servi par Ollama sur le même VPS fonctionne donc. Déclarez le provider dans opencode.json avec le baseURL local et le nom du modèle indiqué par Ollama. La contrainte concerne le matériel : un modèle assez performant pour du développement réel nécessite beaucoup de mémoire. Dimensionnez donc le serveur en fonction du modèle avant de le télécharger.

Comment laisser OpenCode fonctionner après avoir fermé mon ordinateur portable ?

Exécutez-le dans tmux sur le VPS. Démarrez l’agent dans une session nommée avec tmux new -s opencode, détachez-vous avec Ctrl-b puis d, et la session continue de fonctionner sur le serveur après la fermeture de votre connexion SSH. Rattachez-vous à la session à tout moment avec tmux attach -t opencode. La conversation et toute tâche en cours sont toujours présentes. Un redémarrage du serveur met fin à la session. Vous devez donc en démarrer une nouvelle après un reboot.

Est-il prudent d’autoriser OpenCode à exécuter des commandes sur mon VPS ?

C’est maîtrisable si vous l’isolez. Donnez à OpenCode un utilisateur dédié sans privilèges et sans sudo. Conservez ses projets dans git et effectuez un commit avant chaque tâche afin de pouvoir annuler une modification incorrecte. Stockez la clé API dans un fichier avec le mode 600. Utilisez l’agent Plan pour une première analyse avant d’autoriser l’agent Build à modifier quoi que ce soit. Définissez les modifications et les commandes shell sur deny pour Plan si vous voulez que cette étape soit strictement en lecture seule. L’agent ne pourra alors endommager que les éléments appartenant à son propre compte. Le reste du serveur restera inaccessible.

Quelle est la différence entre OpenCode et Claude Code ?

OpenCode est open source (MIT) et indépendant du provider. Il se connecte à plus de 75 providers de modèles, y compris des providers locaux, via une interface unique. Claude Code est l’agent de terminal d’Anthropic, conçu autour des modèles d’Anthropic. Si vous voulez utiliser un seul outil avec plusieurs providers, ou une stack entièrement auto-hébergée avec un modèle local, OpenCode est adapté. Les deux fonctionnent bien sur un VPS dans tmux avec la même configuration d’utilisateur sans privilèges.