OpenHands : agent IA de codage autonome sur votre VPS

OpenHands — l'agent IA qui travaille dans le terminal à votre place

OpenHands repose sur une architecture simple : un serveur web qui orchestre un ou plusieurs agents LLM, chacun s'exécutant dans un sandbox Docker éphémère. L'agent dispose d'un shell, d'un accès au système de fichiers du projet, d'une connexion à l'API GitHub et d'une boucle de raisonnement qui alterne lecture du code, planification et exécution.

Le benchmark SWE-bench Verified mesure la capacité d'un agent à résoudre de vraies issues GitHub sans aide humaine. En avril 2025, OpenHands couplé à Claude Sonnet atteignait 60,6 % sur ce benchmark en trajectoire unique, et 66,4 % avec cinq tentatives et un modèle critique. Pour référence, un développeur junior expérimenté résout environ 15 à 20 % de ces issues — les agents actuels le surpassent largement sur des tâches bien définies et documentées.

OpenHands est distribué sous licence MIT : vous pouvez l'héberger, le modifier et l'intégrer à vos outils internes sans restriction commerciale. Le projet est actif — la v1.23.0 a été publiée le 23 septembre 2026, avec notamment le support de MCP distant et la synchronisation Git pour les administrateurs d'organisation.

Ce qu'OpenHands peut faire seul

Corriger un bug documenté : l'agent lit l'issue GitHub, localise le code incriminé, écrit le correctif, lance les tests existants et ouvre une PR avec un message de commit explicatif.
Ajouter une suite de tests : en partant d'un module non couvert, l'agent génère des tests unitaires ou d'intégration alignés avec le framework existant (pytest, PHPUnit, Jest…).
Refactoriser du code : extraire une fonction, renommer des variables pour respecter les conventions, déplacer un module vers une architecture plus lisible.
Compléter la documentation : générer ou mettre à jour des docstrings, des fichiers README, des exemples d'utilisation d'API à partir du code source.
Analyser un dépôt inconnu : produire un rapport de structure, identifier les dépendances critiques, cartographier les flux de données entre modules.
Ouvrir et décrire une pull request : générer le titre, le corps de PR avec les changements expliqués, les tests passants et les instructions de revue pour l'équipe.

Prérequis chiffrés avant l'installation

OpenHands est un orchestrateur léger, mais il lance des conteneurs sandbox pour chaque tâche. Les besoins varient selon le backend LLM choisi.

Matériel minimum (API cloud — Claude, GPT-4, Gemini) :
- RAM : 4 Go minimum, 8 Go recommandés pour plusieurs tâches simultanées
- CPU : 2 vCPU minimum, 4 vCPU pour un usage fluide
- Stockage : 20 Go libres (images Docker + workspace des projets)
- Système : Linux avec Docker 24+ installé (Ubuntu 22.04 LTS ou Debian 12 recommandés)

Matériel si vous couplé à Ollama pour un LLM local :
- RAM : 16 Go minimum (8 Go pour le modèle 7B quantisé + 4 Go pour le système + marge)
- GPU VRAM : optionnel mais très conseillé — sans GPU, l'inférence est 10 à 30 fois plus lente
- Stockage : 40 Go libres (modèles Ollama + Docker)

Versions logicielles :
- Docker Engine 24.0 ou plus récent (vérifiez avec docker --version)
- Docker Compose v2 (intégré à Docker Desktop et Docker Engine 24+)
- Linux kernel 5.4+ (requis pour le namespace d'isolement du sandbox)

Le port 3000 doit être accessible depuis votre navigateur ou votre VPN. Il est recommandé de ne jamais l'exposer directement sur Internet — utilisez un reverse proxy Nginx avec HTTPS.

Installer OpenHands sur VPS en 8 étapes

Installer Docker Engine sur votre VPS

Sur Ubuntu 22.04 ou Debian 12, installez Docker avec le script officiel :

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

Vérifiez l'installation :

docker --version
# Docker version 27.x.x
docker compose version
# Docker Compose version v2.x.x

02
Créer le répertoire de travail
Créez un dossier dédié pour OpenHands et ses données persistantes :
```
mkdir -p /opt/openhands/.openhands
cd /opt/openhands
```
Le dossier ~/.openhands (ou /opt/openhands/.openhands si vous travaillez en root) stockera la configuration persistante : clés API, historique des conversations, paramètres de l'agent.

Lancer OpenHands avec Docker

Démarrez OpenHands avec la commande officielle :

docker run -it --rm --pull=always \
  -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:latest \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/openhands/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.all-hands.dev/all-hands-ai/openhands:latest

Le flag --pull=always garantit que vous exécutez la dernière image stable. OpenHands est accessible sur http://localhost:3000 (ou via votre reverse proxy).

Pour un déploiement permanent (redémarrage automatique), ajoutez --restart unless-stopped et retirez -it --rm.

Alternative : déployer avec Docker Compose

Pour une gestion plus simple, créez un fichier compose.yml dans /opt/openhands :

services:
  openhands:
    image: docker.all-hands.dev/all-hands-ai/openhands:latest
    container_name: openhands-app
    pull_policy: always
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./.openhands:/.openhands
    extra_hosts:
      - host.docker.internal:host-gateway
    restart: unless-stopped

Lancez la stack :

docker compose up -d
docker compose logs -f

Configurer le backend LLM dans l'interface
Ouvrez http://localhost:3000 (ou votre domaine HTTPS). Au premier démarrage, OpenHands demande :
1. Le fournisseur LLM : choisissez Anthropic, OpenAI, Google, ou openai-compatible pour Ollama
2. Le modèle : claude-sonnet-4-5 (rapport qualité/coût optimal) ou claude-opus-4-5 pour les tâches complexes
3. La clé API : collez votre clé Anthropic ou OpenAI
Ces paramètres sont sauvegardés dans ~/.openhands/config.toml et persistent entre les redémarrages.
Connecter OpenHands à GitHub
Pour qu'OpenHands puisse cloner des dépôts privés, lire les issues et ouvrir des PRs, configurez un Personal Access Token GitHub :
1. Sur GitHub : Settings → Developer settings → Personal access tokens → Fine-grained tokens
2. Accordez les permissions : Contents (read/write), Pull requests (read/write), Issues (read)
3. Dans l'interface OpenHands : Settings → Git → collez le token
Avec ce token, tapez simplement l'URL d'une issue dans le champ de tâche et OpenHands prend le relais.

Configurer le reverse proxy Nginx avec HTTPS

N'exposez jamais le port 3000 directement. Utilisez Nginx comme reverse proxy :

server {
    listen 443 ssl;
    server_name openhands.votre-domaine.com;

    ssl_certificate /etc/letsencrypt/live/openhands.votre-domaine.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openhands.votre-domaine.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_http_version 1.1;
        proxy_read_timeout 600s;
    }
}

Obtenir le certificat :

certbot --nginx -d openhands.votre-domaine.com

Le proxy_read_timeout 600s est important : les tâches longues (analyse complète d'un dépôt, résolution d'une issue complexe) peuvent prendre plusieurs minutes.

Tester avec une première tâche
Ouvrez l'interface, collez une issue GitHub (ex. https://github.com/votre-org/votre-repo/issues/42) dans le champ de tâche, et cliquez Start.
OpenHands va :
1. Lire l'issue et planifier l'approche
2. Cloner le dépôt dans le sandbox
3. Explorer le code, écrire les modifications
4. Lancer les tests (pytest, npm test, etc.)
5. Afficher un résumé et proposer d'ouvrir une PR
Suivez l'exécution en temps réel dans l'onglet Trajectory — chaque action de l'agent (lecture de fichier, commande shell, écriture de code) est tracée et peut être rejouée.

Configurer le backend IA : Claude, GPT-4 ou Ollama

OpenHands supporte tout fournisseur compatible avec l'API OpenAI, ainsi que les fournisseurs natifs Anthropic, Google et Azure. Le choix du modèle est le facteur le plus déterminant sur la qualité des résultats.

Claude Sonnet (Anthropic) — recommandé pour la production
Claude claude-sonnet-4-5 est le modèle qui offre un excellent rapport qualité/coût pour l'ingénierie logicielle agentique. Sa fenêtre de contexte de 200 000 tokens lui permet d'analyser de larges bases de code sans pagination. Comptez quelques centimes de dollar par tâche selon la complexité. Configurez LLM_MODEL=anthropic/claude-sonnet-4-5 dans vos variables d'environnement ou dans config.toml.

Claude Opus (Anthropic) — pour les tâches complexes
claude-opus-4-5 offre d'excellentes performances sur les problèmes architecturaux et les refactorings larges, mais à un coût 5 à 10 fois supérieur à Sonnet. Réservez-le aux tâches qui dépassent Sonnet.

Ollama (LLM local) — pour la souveraineté totale
Si votre code est particulièrement sensible ou si vous souhaitez zéro dépendance externe, couplé OpenHands à Ollama sur le même VPS. Configurez LLM_BASE_URL=http://host.docker.internal:11434 et LLM_MODEL=openai/qwen2.5-coder:32b. Les modèles qwen2.5-coder 32B donnent d'excellents résultats parmi les modèles open weights sur les benchmarks de codage. Inconvénient : l'inférence sur CPU est 10 à 30 fois plus lente qu'un appel API — comptez 1 à 5 minutes par sous-tâche.

Variables d'environnement clés :

LLM_MODEL=anthropic/claude-sonnet-4-5
LLM_API_KEY=sk-ant-...
LLM_BASE_URL=         # vide pour Anthropic, URL Ollama pour local
AGENT=CodeActAgent    # agent par défaut, performant sur SWE-bench

Sécuriser docker.sock — socket proxy et mode rootless. Monter /var/run/docker.sock dans un conteneur est équivalent à donner un accès root complet à la machine hôte : tout conteneur ayant accès à ce socket peut créer de nouveaux conteneurs, monter des volumes arbitraires, et escalader ses privilèges.

Deux approches pour réduire cette surface d'attaque :

Option 1 — Socket proxy (Tecnativa/socket-proxy) : interposez un proxy qui filtre les appels à l'API Docker. OpenHands n'a besoin que de POST /containers/create, GET /containers/{id}/json, POST /containers/{id}/start et DELETE /containers/{id}. Le socket proxy bloque tout le reste.

services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy
    environment:
      CONTAINERS: 1
      POST: 1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

  openhands:
    image: docker.all-hands.dev/all-hands-ai/openhands:latest
    environment:
      - DOCKER_HOST=tcp://socket-proxy:2375
    depends_on:
      - socket-proxy
    # Ne plus monter docker.sock directement
    restart: unless-stopped

Option 2 — Docker rootless : exécutez Docker en mode rootless (votre utilisateur système, pas root). Le socket est alors sous /run/user/1000/docker.sock et appartient à votre utilisateur. Un compromis de ce socket n'escalade pas au-delà des droits de cet utilisateur. Activez-le avec dockerd-rootless-setuptool.sh install.

Cas d'usage concrets

Cas 1 — Résoudre un bug documenté dans une issue GitHub
Copier l'URL d'une issue bien décrite (comportement attendu, comportement observé, stack trace si disponible) dans OpenHands. L'agent lit l'issue, cherche les fichiers concernés avec grep et l'explorateur de code, écrit le correctif, lance la suite de tests et propose une PR. Sur des bugs isolés avec une bonne issue, le taux de succès est élevé sans intervention humaine.

Cas 2 — Générer les tests d'un module non couvert
Indiquez le module cible : Écris les tests unitaires pour le module src/payments/stripe.py, en ciblant 80 % de couverture avec pytest. Les mocks doivent utiliser unittest.mock. L'agent analyse le module, identifie les cas limites et génère une suite de tests cohérente avec les patterns existants du projet.

Cas 3 — Analyser un dépôt open source avant de le forker
Avant d'intégrer une dépendance ou de forker un projet, demandez à OpenHands : Analyse le dépôt https://github.com/org/repo. Identifie les dépendances critiques, les points de couplage fort, les tests manquants et les CVE connues dans les dépendances directes. L'agent produit un rapport structuré en quelques minutes.

Cas 4 — Mettre à jour une dépendance majeure
Les migrations de versions majeures (Django 4 → 5, React 18 → 19, Laravel 10 → 11) impliquent de nombreux fichiers. OpenHands peut lire le changelog officiel, identifier les breaking changes, les appliquer mécaniquement et relancer les tests pour identifier ce qui reste à corriger manuellement.

Dépannage — erreurs courantes

permission denied while trying to connect to the Docker daemon socket
L'utilisateur qui exécute OpenHands n'est pas dans le groupe docker. Corrigez avec :

sudo usermod -aG docker $USER && newgrp docker

Si vous montez le socket dans un conteneur, vérifiez que le GID du socket correspond au GID attendu par OpenHands.

Container exited with OOM kill (exit code 137)
Le sandbox a manqué de mémoire. Augmentez la RAM disponible sur le VPS ou limitez le nombre de tâches parallèles. Ajoutez --memory=4g au conteneur sandbox dans la configuration OpenHands.

LLM timeout after 120s
Sur des bases de code larges, l'agent envoie de gros contextes au LLM. Deux solutions : (a) augmentez LLM_TIMEOUT dans la configuration, (b) passez à un modèle avec une fenêtre de contexte plus grande ou réduisez le scope de la tâche.

No such container: openhands-sandbox-xxx
Le conteneur sandbox a été supprimé entre deux actions. Cela arrive quand Docker est redémarré pendant une tâche. Relancez la tâche depuis le début — OpenHands ne reprend pas les tâches interrompues par un redémarrage Docker.

Rate limit exceeded (Anthropic/OpenAI)
OpenHands fait beaucoup d'appels LLM sur une tâche complexe. Si vous atteignez les limites de taux, ajoutez LLM_NUM_RETRIES=5 et LLM_RETRY_MIN_WAIT=30 dans la configuration pour laisser OpenHands réessayer automatiquement.

OpenHands vs Codex cloud vs Devin

Faites défiler le tableau

Critère	OpenHands self-hosted	GitHub Copilot Workspace	Devin (Cognition)
Coût mensuel	0 € (+ coût LLM API)	19 $/mois (Copilot Pro)	500 $/mois (plan Team)
Code envoyé vers l'extérieur	Non (code reste sur le VPS)	Oui (GitHub/Microsoft)	Oui (Cognition)
Backend LLM configurable	Oui (Claude, GPT, Ollama…)	Non (modèle Microsoft)	Non (modèle Cognition)
Score SWE-bench Verified	66,4 % (5 tentatives, Claude)	Non publié	~49 % (dernière publication)
Licence	MIT (open source)	Propriétaire	Propriétaire (SaaS)
VPS requis	Oui (4 Go RAM min)	Non	Non
Autonomie complète (PR auto)	Oui	Partielle	Oui

OpenHands : agent IA de codage autonome sur votre VPS

OpenHands — l'agent IA qui travaille dans le terminal à votre place

Ce qu'OpenHands peut faire seul

Prérequis chiffrés avant l'installation

Installer OpenHands sur VPS en 8 étapes

Installer Docker Engine sur votre VPS

Créer le répertoire de travail

Lancer OpenHands avec Docker

Alternative : déployer avec Docker Compose

Configurer le backend LLM dans l'interface

Connecter OpenHands à GitHub

Configurer le reverse proxy Nginx avec HTTPS

Tester avec une première tâche

Configurer le backend IA : Claude, GPT-4 ou Ollama

Cas d'usage concrets

Dépannage — erreurs courantes

OpenHands vs Codex cloud vs Devin

Déployez OpenHands sur un VPS ServOrbit

Articles liés

Comment héberger Flowise sur un VPS

GitHub Copilot AI Credits : reprendre le contrôle sur un VPS

Héberger Hermes Agent sur un VPS

Besoin d'aide ?