Auto-héberger OpenHands sur un VPS

Ce qu'est OpenHands, et le premier risque à comprendre

OpenHands, anciennement OpenDevin, est un agent autonome de génie logiciel. Vous lui donnez une tâche en langage courant, et il planifie le travail, écrit du code, exécute des commandes, lit la sortie et itère jusqu'à ce que la tâche soit terminée. Vous le faites tourner sur votre propre serveur avec Docker et vous le connectez à un modèle de langage. Sur un VPS, il devient un agent de codage qui travaille pendant que vous êtes absent.

Un seul fait devrait orienter toute votre installation. OpenHands ne se contente pas de suggérer du code, il l'exécute, et pour cela son conteneur contrôleur monte le socket Docker de l'hôte sur /var/run/docker.sock afin de pouvoir lancer des conteneurs bac à sable pour chaque tâche. Tout ce qui peut 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, ce qui signifie que l'accès au socket équivaut à root sur la machine. Traitez donc la machine OpenHands comme un serveur qui exécute du code non fiable, car c'est exactement ce qu'elle fait. Chaque choix de durcissement ci-dessous en découle.

Ce dont vous avez besoin

Vous avez besoin d'un VPS sous Ubuntu 24.04 avec une version récente de Docker Engine, d'au moins 4 Go de RAM et d'une clé 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 revient donc. Si vous n'avez jamais configuré de conteneurs auparavant, les bases de Docker sur un VPS couvrent les prérequis que ce guide suppose acquis.

Installer avec Docker

OpenHands est distribué sous forme de deux images : l'image d'application que vous exécutez, et une image agent-server qu'il télécharge pour exécuter le bac à sable de chaque tâche. Lancez-le ainsi, en remplaçant les tags actuels 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 vous épargneront une heure de confusion. L'image d'application et l'image agent-server portent volontairement des numéros de version différents, donc n'essayez pas de les faire correspondre : utilisez le tag agent-server que la documentation associe à votre version d'application. Et remarquez le -p 127.0.0.1:3000:3000 plutôt que -p 3000:3000. Ce seul changement fait toute la différence entre une interface Web que vous seul pouvez atteindre et une que l'internet entier peut atteindre, ce qui est le sujet de la section suivante.

Gardez l'interface Web hors de l'internet public

OpenHands sert son interface sur le port 3000. Cette interface pilote un agent qui exécute du code, donc la publier sur internet offre à quiconque la trouve un accès distant à un processus qui exécute des commandes. Liez-la à l'interface de bouclage (loopback), comme le fait la commande ci-dessus, et atteignez-la 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 emprunte votre session SSH existante, et rien de nouveau n'écoute sur l'internet public. Pour une configuration plus permanente, placez-la plutôt derrière un VPN. Dans les deux cas, placez un pare-feu en refus par défaut devant la machine afin que rien ne soit exposé par accident, et rappelez-vous qu'un pare-feu couvrant uniquement IPv4 laisse le même port ouvert en IPv6, ce qui est la faille de pare-feu IPv6 qui piège tant de gens.

Isolez la clé du modèle et les identifiants de dépôt

OpenHands a besoin d'une clé API pour son modèle, et souvent d'un jeton pour cloner vos dépôts et y pousser du code. Les deux peuvent dépenser de l'argent et agir en votre nom, alors traitez-les comme des mots de passe. Conservez-les dans un fichier d'environnement que seul le bon compte peut lire, jamais dans la commande de lancement où ils finissent dans l'historique de votre shell et la liste des processus, et jamais dans un fichier au sein d'un dépôt git.

Faites-le tourner sur une machine jetable

Parce que le contrôleur doit détenir le socket Docker, vous ne pouvez pas isoler complètement OpenHands de son hôte dans un bac à sable. L'atténuation honnête est l'isolation par le placement : faites tourner OpenHands sur un VPS dédié qui n'héberge rien d'autre qui compte pour vous, pas sur le serveur qui héberge aussi votre base de données ou votre site web. Prenez un instantané avant de commencer, et reconstruisez à partir de cet instantané plutôt que de faire confiance à une machine qui a exécuté du code écrit par l'agent pendant une semaine. Un VPS bon marché, jetable et à usage unique est le bon foyer pour lui.

Durcissez la machine autour de lui

Le reste relève de l'hygiène standard d'un serveur, et cela compte davantage ici que d'habitude parce que la charge de travail est plus risquée que d'habitude. Créez un utilisateur administrateur non privilégié plutôt que de travailler en tant que root, en suivant l'exécution des services avec un utilisateur non privilégié. Passez SSH à une authentification par clé uniquement. Puis parcourez la liste de contrôle ci-dessous et gardez-la quelque part où vous la reverrez.

Pour comprendre les rouages plutôt que de simplement les exécuter, voyez comment construire votre propre agent IA sur un VPS ; pour une plateforme moins axée sur le code, l'auto-hébergement de Dify est une entrée en matière plus douce.

FAQ

Est-il sûr d'exécuter OpenHands sur un serveur ?

Cela peut l'être, avec précaution, mais c'est plus risqué qu'une application web ordinaire parce qu'il écrit et exécute du code et que son contrôleur détient le socket Docker de l'hôte, ce qui équivaut à root sur la machine. Faites-le tourner sur un VPS dédié et jetable qui n'héberge rien d'autre de précieux, gardez son interface Web sur le bouclage derrière un tunnel SSH ou un VPN, isolez ses clés et durcissez la machine. Ne le faites pas tourner à côté de vos services importants.

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

OpenHands exécute chaque tâche dans un nouveau conteneur bac à sable, et 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. Cela donne au conteneur contrôleur le contrôle de Docker sur l'hôte, ce qui est puissant et risqué, si bien que l'hôte lui-même doit être traité comme un hôte qui exécute du code non fiable.

OpenHands peut-il utiliser un modèle local plutôt qu'une API payante ?

Oui. OpenHands prend en charge les modèles locaux servis par Ollama ou vLLM, vous pouvez donc l'auto-héberger entièrement sans coût au jeton et sans qu'aucune donnée ne quitte votre serveur. Il vous faut une machine avec assez de mémoire pour un modèle de codage performant, ce qui est la même question de dimensionnement que celle abordée dans le guide Ollama.

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

Non. Parce qu'il exécute du code écrit par l'agent et détient le socket Docker, gardez-le sur un VPS distinct, à usage unique, que vous êtes prêt à reconstruire. Le placer avec une base de données, un site web ou vos autres services signifie qu'une erreur de l'agent, ou un bug dans celui-ci, peut atteindre des choses qu'il n'était jamais censé toucher.