Installer OpenHands sur un VPS avec Docker

Ce qu’est OpenHands et le seul risque à comprendre en premier

OpenHands, anciennement OpenDevin, est un agent autonome d’ingénierie logicielle. Vous lui donnez une tâche en langage courant. Il planifie le travail, écrit du code, exécute des commandes, lit la sortie et recommence jusqu’à ce que la tâche soit terminée. Vous l’exécutez sur votre propre serveur avec Docker et vous le connectez à un modèle de langage. Sur un VPS, il devient un agent de développement qui travaille pendant votre absence.

Un fait doit guider toute votre configuration. OpenHands ne se contente pas de suggérer du code : il l’exécute. Pour cela, son conteneur contrôleur monte le socket Docker de l’hôte à /var/run/docker.sock afin de pouvoir créer des conteneurs sandbox pour chaque tâche. Tout processus capable de communiquer avec le socket Docker peut démarrer un nouveau conteneur qui monte l’intégralité du système de fichiers de l’hôte. L’accès au socket équivaut donc en pratique à un accès root sur la machine. Traitez donc le serveur OpenHands comme un serveur qui exécute du code non fiable, car c’est exactement ce qu’il fait. Toutes les mesures de sécurisation ci-dessous en découlent.

Ce dont vous avez besoin

Vous avez besoin d’un VPS sous Ubuntu 24.04 avec une version récente de Docker Engine, au moins 4 Go de RAM et une clé d’API pour un modèle de langage (OpenAI, Anthropic ou Google), ou d’un modèle local servi par Ollama sur le même VPS. OpenHands prend en charge des dizaines de backends de modèles : le choix vous appartient. Si vous n’avez jamais configuré de conteneurs, les bases de Docker sur un VPS couvrent les notions utilisées dans ce guide.

Installation avec Docker

OpenHands est fourni sous la forme de deux images : l’image de l’application que vous exécutez et une image agent-server qu’il télécharge pour exécuter le sandbox de chaque tâche. Lancez-le comme suit, en remplaçant les tags par ceux actuellement indiqués dans la documentation du projet :

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands \
  docker.openhands.dev/openhands/openhands:1.8

Deux détails évitent une heure de confusion. L’image de l’application et l’image agent-server utilisent volontairement des numéros de version différents. N’essayez donc pas de les faire correspondre : utilisez le tag agent-server associé à la version de votre application dans la documentation. Notez également la présence de -p 127.0.0.1:3000:3000 à la place de -p 3000:3000. Cette seule modification détermine si seule votre interface Web est accessible ou si elle est accessible depuis tout Internet. La section suivante explique ce point.

Ne laissez pas l’interface Web accessible depuis Internet

OpenHands expose son interface sur le port 3000. Cette interface pilote un agent qui exécute du code. La publier sur Internet donne donc à toute personne qui la découvre un accès distant à un processus capable d’exécuter des commandes. Liez-la à l’interface loopback, comme dans la commande précédente, puis accédez-y depuis votre ordinateur portable via un tunnel SSH :

ssh -L 3000:127.0.0.1:3000 you@your-vps

Ouvrez ensuite http://127.0.0.1:3000 sur votre propre machine. Le trafic passe par votre session SSH existante. Aucun nouveau service n’est donc en écoute sur Internet. Tous les agents n’ont pas besoin d’un port : les sessions Claude Code sur le même VPS communiquent entre elles via le terminal, de sorte que le seul service que vous exposez est SSH. La même méthode, qui consiste à utiliser loopback et un tunnel, s’applique à tous les tableaux de bord d’agents que vous hébergez ; accéder à l’interface de scan d’open-kritt via un tunnel fonctionne de la même manière, mais sur le port 5173. Pour une configuration plus permanente, placez plutôt le service derrière un VPN. Dans tous les cas, placez un firewall configuré en refus par défaut devant le serveur afin que rien ne soit exposé par accident. N’oubliez pas non plus qu’un firewall qui ne couvre qu’IPv4 laisse le même port ouvert sur IPv6. C’est la faille de firewall IPv6 qui prend tant de personnes au dépourvu.

Isoler la clé du modèle et les identifiants des dépôts

OpenHands a besoin d’une clé API pour son modèle et, souvent, d’un token pour cloner et pousser vers vos dépôts. Ces deux éléments peuvent entraîner des frais et agir en votre nom. Traitez-les donc comme des mots de passe. Conservez-les dans un fichier d’environnement que seul le compte concerné peut lire. Ne les indiquez jamais dans la commande de lancement, car ils apparaîtraient dans l’historique de votre shell et dans la liste des processus. Ne les stockez jamais non plus dans un fichier situé dans un dépôt git. Si vous conservez les originaux dans un gestionnaire de mots de passe auto-hébergé, sécurisez également ce serveur. Les points faibles d’un coffre sont généralement son token d’administration et son fichier de sauvegarde, plutôt que les éléments chiffrés eux-mêmes, comme l’explique le guide de sécurisation de Vaultwarden.

Exécutez-le sur un serveur que vous pouvez jeter

Comme le contrôleur doit avoir accès au socket Docker, vous ne pouvez pas isoler complètement OpenHands de son hôte. La mesure d’atténuation réaliste consiste à l’isoler par son emplacement : exécutez OpenHands sur un VPS dédié qui ne contient rien d’important pour vous, et non sur le serveur qui héberge aussi votre base de données ou votre site web. Prenez un instantané avant de commencer, puis recréez le serveur à partir de cet instantané au lieu de faire confiance à une machine qui a exécuté pendant une semaine du code généré par l’agent. Un VPS bon marché, jetable et réservé à cet usage est l’emplacement adapté. Ici, l’emplacement est le seul levier qu’OpenHands vous offre réellement. Si vous souhaitez aussi contrôler ce que l’agent peut faire avant de s’arrêter pour vous demander confirmation, les modes d’autorisation de Claude Code montrent à quoi ressemble ce deuxième levier sur un serveur que personne ne surveille.

Renforcez la sécurité du serveur

Le reste relève de l’hygiène standard d’un serveur. Elle est encore plus importante ici, car la charge de travail présente plus de risques que d’habitude. Créez un utilisateur administrateur non privilégié au lieu de travailler avec root, en suivant exécuter des services avec un utilisateur non privilégié. Configurez ensuite SSH pour utiliser uniquement l’authentification par clé. Exécutez enfin la checklist ci-dessous et conservez-la à un endroit où vous la reverrez.

Pour comprendre les différents composants au lieu de simplement les exécuter, consultez créer votre propre agent IA sur un VPS ; pour une plateforme nécessitant moins de code, auto-héberger Dify constitue une introduction plus progressive.

FAQ

OpenHands peut-il être exécuté sur un serveur ?

Oui, mais avec des précautions. OpenHands est plus risqué qu’une application web classique, car il écrit et exécute du code, et son contrôleur détient le socket Docker de l’hôte, ce qui revient en pratique à disposer des privilèges root sur la machine. Exécutez-le sur un VPS dédié et jetable, qui ne contient aucune autre donnée importante. Gardez son interface web liée à la boucle locale, derrière un tunnel SSH ou un VPN. Isolez ses clés et durcissez le serveur. Ne l’exécutez pas à côté de vos services importants.

Pourquoi OpenHands a-t-il besoin du socket Docker ?

OpenHands exécute chaque tâche dans un conteneur sandbox neuf. Il demande au démon Docker de l’hôte de créer ces conteneurs en montant /var/run/docker.sock dans son contrôleur. Le conteneur du contrôleur dispose ainsi du contrôle de Docker sur l’hôte. C’est puissant et risqué. L’hôte doit donc être considéré comme une machine qui exécute du code non fiable.

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

Oui. OpenHands prend en charge les modèles locaux servis par Ollama ou vLLM. Vous pouvez donc l’exécuter entièrement en auto-hébergement, sans coût par token et sans que les données quittent votre serveur. Il vous faut une machine disposant de suffisamment de mémoire pour exécuter un modèle de programmation performant. C’est le même problème de dimensionnement que celui traité dans le guide consacré à Ollama.

Dois-je exécuter OpenHands sur mon serveur principal ?

Non. Comme il exécute du code écrit par un agent et détient le socket Docker, installez-le sur un VPS séparé, dédié à cet usage, que vous êtes prêt à reconstruire. Le faire cohabiter avec une base de données, un site web ou vos autres services signifie qu’une erreur de l’agent, ou un bug dans OpenHands, peut atteindre des ressources auxquelles il ne devrait jamais accéder.