Déploiement d’OpenHands Agent Canvas sur un VM distant

Ce guide accompagne les développeurs et équipes DevOps depuis le premier démarrage privé jusqu’à la mise en production d’OpenHands Agent Canvas sur un VM distant. Vous y trouverez les limites de l’exécution directe, les contrôles de sécurité, la conservation des tâches après une déconnexion SSH, le changement de backend et les conditions justifiant un Mac distant.

Symptôme : votre ordinateur portable se met en veille et une longue tâche OpenHands s’arrête avec lui.
Solution la plus rapide : déployez Agent Canvas sur un VM indépendant et reconstruisible, validez-le en réseau privé, puis ajoutez clé API, TLS, supervision et sandbox avant toute ouverture publique.

Ce choix concerne surtout les développeurs dont les tâches dépassent la durée d’une session locale, les équipes DevOps qui doivent fournir un backend Agent partagé et les responsables qui préparent des compilations macOS ou multiplateformes. Si votre dépôt exige Xcode, un simulateur Apple ou une signature native, vous ajouterez ensuite un Mac distant ; pour le reste, le VM Linux doit rester votre environnement principal.

Dernière mise à jour : 14 août 2026. Les commandes, ports et relations entre services ont été vérifiés dans le guide officiel d’auto-hébergement d’Agent Canvas, le README officiel d’OpenHands, et la documentation Agent Server.

Le bon périmètre d’exécution

Un VM dédié est préférable à votre poste personnel pour trois raisons concrètes. D’abord, il reste actif lorsque votre écran est fermé, votre réseau change ou votre ordinateur redémarre. Ensuite, il sépare les clés, dépôts et variables utilisés par l’agent de votre environnement quotidien. Enfin, il peut être détruit puis recréé à partir d’une procédure documentée, ce qui est plus sain qu’une machine personnelle devenue progressivement impossible à auditer.

Le point important est de ne pas confondre trois frontières :

Le contrôle : l’interface Agent Canvas et le routage des requêtes.
L’exécution : Agent Server, les commandes shell, les fichiers et les outils de développement.
Le sandbox : un conteneur Docker ou un autre environnement isolé dans lequel l’agent travaille.

Le modèle officiel présente Agent Canvas comme une interface pouvant se connecter à plusieurs Agent Servers. Un Agent Server fournit l’API HTTP et les flux WebSocket ; l’espace de travail exécute ensuite les commandes et conserve les fichiers nécessaires à la conversation. Cette séparation permet de basculer entre une machine locale, un VM ou un nœud dédié sans réécrire la logique de l’agent. (github.com)

Avant de créer la machine, écrivez ce que le VM est autorisé à faire :

héberger uniquement le contrôle et l’interface ;
lire un ou plusieurs dépôts et les construire directement ;
transmettre l’exécution à un Docker Sandbox ;
accéder au réseau sortant, à un registre Git ou à des services de test ;
utiliser des secrets de développement, ou n’en recevoir aucun.

Une installation directe est la plus courte, mais l’agent peut alors lire le système de fichiers, exécuter des commandes et utiliser le réseau de l’hôte. La documentation officielle avertit explicitement que cette machine doit être traitée comme un serveur contenant des informations sensibles. Le Docker Sandbox réduit la portée d’une erreur, mais ne rend pas inutile le pare-feu, la gestion des secrets ou la limitation des volumes montés.

La première mise en route privée

L’objectif de cette phase n’est pas de fournir une URL publique. Il consiste à prouver que l’interface, le backend, le dépôt et le flux d’événements fonctionnent ensemble avec la plus petite surface réseau possible.

Le guide officiel actuel utilise Node.js 22.12.x ou une version ultérieure, uv, ainsi que curl et git sur Ubuntu. Le même guide indique qu’un hôte Linux ou macOS toujours disponible convient, avec un exemple de machine capable de servir un utilisateur unique ; ne transformez toutefois pas cette indication en capacité garantie pour plusieurs agents concurrents. La charge réelle dépend du modèle utilisé, du dépôt, des compilations et du nombre de conversations simultanées. (github.com)

Sur un VM Linux, préparez d’abord l’environnement :

sudo apt-get update
sudo apt-get install -y curl git

curl -LsSf https://astral.sh/uv/install.sh | sh

Installez ensuite Node.js avec votre méthode d’administration habituelle, puis vérifiez les deux dépendances :

node --version
uv --version

Pour la première exécution, générez une clé distincte de vos clés de dépôt ou de fournisseur LLM :

export LOCAL_BACKEND_API_KEY=$(openssl rand -base64 32)
npx @openhands/agent-canvas --public

Dans le modèle officiel, cette commande démarre le serveur statique, Agent Server et le backend d’automatisation derrière un proxy d’entrée local. Le schéma documenté utilise 127.0.0.1:8000 comme point d’entrée, tandis que les services internes sont associés aux ports 3001, 18000 et 18001. Ces valeurs décrivent le lancement officiel vérifié au moment de la rédaction ; elles ne doivent pas être remplacées par une règle générale pour les futures versions. (github.com)

Gardez le service privé et ouvrez un tunnel depuis votre poste :

ssh -N -L 8000:127.0.0.1:8000 utilisateur@adresse-du-vm

Accédez ensuite à l’interface via http://localhost:8000. Cette méthode vous permet d’inspecter l’installation sans exposer Agent Canvas au réseau public. Si vous préférez un VPN, conservez la même logique : les ports internes restent inaccessibles depuis Internet et seuls les membres du réseau privé peuvent atteindre le point d’entrée.

Ne passez à la suite que lorsque vous avez obtenu les quatre preuves suivantes :

l’interface s’affiche dans le navigateur ;
le backend apparaît comme connecté ;
le dépôt de test est lisible depuis le bon répertoire ;
une tâche simple produit des événements continus jusqu’à sa fin.

Une page qui s’ouvre ne suffit pas. Un écran accessible avec un backend mal configuré peut donner l’impression que le déploiement fonctionne alors que les commandes, les fichiers ou le flux temps réel échoueront dès la première tâche longue.

La sécurité avant le premier dépôt sensible

Le risque principal n’est pas le port d’interface en lui-même : c’est le pouvoir accordé à l’agent sur l’hôte. En exécution directe, une mauvaise instruction, une extension compromise ou un dépôt contenant une commande dangereuse peut atteindre d’autres fichiers, variables d’environnement et services accessibles depuis la machine.

Commencez par limiter le répertoire de travail. Ne montez pas votre dossier personnel complet si le dépôt exige seulement un sous-répertoire. Évitez également d’ajouter des fichiers .env, des clés SSH privées ou des jetons de production dans l’espace visible par l’agent. Les secrets doivent être injectés uniquement lorsque la tâche les nécessite, avec une portée et une durée contrôlées.

La clé LOCAL_BACKEND_API_KEY ne doit apparaître ni dans un dépôt public, ni dans le code JavaScript livré au navigateur, ni dans des journaux accessibles aux utilisateurs. Le mode --public est important précisément parce qu’il évite d’intégrer automatiquement la clé dans l’interface ; l’utilisateur doit la saisir avant d’utiliser le backend. Toute personne qui possède cette clé peut toutefois envoyer des requêtes autorisées au serveur : traitez-la donc comme un secret opérationnel, et non comme un simple mot de passe d’écran. (github.com)

Pour choisir entre exécution directe et Docker Sandbox, utilisez cette règle :

Directe : acceptable pour un VM éphémère, un dépôt non sensible et une équipe qui contrôle entièrement l’hôte.
Docker Sandbox : préférable lorsque l’agent doit modifier un projet sans pouvoir parcourir le reste du système.
Nœud séparé : nécessaire lorsque le dépôt contient des secrets, des outils privilégiés ou des dépendances dont l’installation ne doit pas affecter les autres utilisateurs.

Le README officiel fournit un exemple Docker avec un répertoire PROJECTS_PATH monté dans /projects et un volume séparé pour les données OpenHands. Le conteneur ne doit donc recevoir que les dossiers dont vous acceptez l’accès. Le montage de /var/run/docker.sock, lorsqu’il est utilisé dans une architecture de serveur, mérite une revue de sécurité particulière : il peut donner au processus un pouvoir très large sur le moteur Docker. (github.com)

Avant de connecter un dépôt réel, exécutez un test de frontière :

demandez la lecture d’un fichier explicitement autorisé ;
demandez la lecture d’un fichier voisin mais interdit ;
vérifiez qu’une requête sans clé ou avec une clé incorrecte est rejetée ;
testez une commande dangereuse en environnement de test ;
inspectez les journaux pour confirmer qu’aucun secret n’y apparaît.

Rappel de sécurité : un sandbox n’est pas une autorisation générale. Il faut encore limiter les volumes, le réseau sortant, les comptes système, les variables d’environnement et les identités Git utilisées par le dépôt.

La persistance et le service public

Une tâche qui survit à la fermeture SSH doit être lancée par un superviseur, pas par votre terminal. Pour un essai rapide, tmux suffit :

export LOCAL_BACKEND_API_KEY="votre-cle-conservee"
tmux new-session -d -s canvas \
  'npx @openhands/agent-canvas --public'

Pour un service durable, utilisez systemd ou l’outil de supervision déjà standardisé dans votre équipe. Un exemple minimal, dérivé du guide officiel, ressemble à ceci :

[Unit]
Description=Agent Canvas
After=network.target

[Service]
Environment=LOCAL_BACKEND_API_KEY=votre-cle-conservee
ExecStart=/chemin/vers/npx @openhands/agent-canvas --public
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Après création du fichier de service :

sudo systemctl daemon-reload
sudo systemctl enable --now agent-canvas
sudo systemctl status agent-canvas

Dans un déploiement public, le proxy inverse doit être le seul composant exposé. Le guide officiel indique que nginx peut transmettre vers le point d’entrée local unique, avec les chemins d’API, les sockets et l’automatisation routés par ce proxy. Vous devez préserver les connexions persistantes nécessaires aux événements temps réel ; une configuration qui ne transmet que les requêtes HTTP courtes peut afficher l’interface tout en interrompant les tâches en cours.

Le parcours recommandé est donc :

réserver un nom DNS vers l’adresse du VM ;
ouvrir uniquement SSH depuis vos adresses d’administration ;
ouvrir 80 et 443 seulement si l’accès public est réellement nécessaire ;
installer le certificat TLS ;
transmettre les requêtes vers 127.0.0.1:8000 ;
tester la connexion d’événements, puis le renouvellement du certificat ;
vérifier la rotation des journaux et l’absence de clé dans les traces.

Ne publiez pas séparément 18000, 18001, 3001 ou 8000. Le fait qu’un service écoute sur un port ne signifie pas qu’il doit être accessible depuis Internet. La liste des ports doit venir du modèle de déploiement choisi et de la configuration effectivement installée, pas d’un exemple copié sans vérification.

Le basculement entre les backends

Si vous utilisez déjà Agent Canvas en local, vous pouvez enregistrer le VM comme backend supplémentaire. Dans l’interface locale, ajoutez un backend avec :

un nom mémorisable ;
l’URL HTTPS du VM, ou http://localhost:8000 si vous passez encore par le tunnel SSH ;
la valeur de LOCAL_BACKEND_API_KEY.

Le README officiel décrit Agent Canvas comme une interface capable de se connecter à plusieurs Agent Servers et de basculer entre eux. Cette fonction est utile pour séparer les tâches : analyse rapide sur le poste local, exécution persistante sur le VM, compilation native sur un nœud macOS. (github.com)

Le piège est de croire que ce basculement synchronise automatiquement les fichiers non commités. Il ne le fait pas. Le backend distant voit son propre espace de travail. Vous devez donc choisir une méthode explicite :

pousser une branche Git avant de changer de backend ;
cloner le dépôt directement sur le VM ;
transférer un correctif ou une archive pour un test ponctuel ;
utiliser un stockage partagé uniquement après avoir évalué les permissions et les conflits.

Après le changement, vérifiez le chemin du dépôt, la branche, la configuration Agent, les variables attendues et l’historique de conversation. Une tâche qui réussit sur le mauvais clone est un échec de plateforme, même si son journal semble correct.

La décision concernant un Mac distant

Un VM Linux convient à l’analyse de code, aux tests de services Web, aux outils Git, aux applications backend et à la plupart des pipelines qui ne dépendent pas du système Apple. Il est généralement plus facile à reconstruire, à automatiser et à isoler pour ces tâches.

Le Mac distant intervient lorsque le dépôt exige Xcode, un simulateur iOS, les frameworks macOS, une signature de code, des outils audio ou vidéo natifs, ou une validation qui ne peut pas être reproduite sous Linux. Pour un projet de design interactif, de montage automatisé ou de développement Apple, le nœud macOS doit être traité comme une cible spécialisée, et non comme le remplacement universel du VM.

Dans ce cas, utilisez une règle de routage simple :

dépôt sans outil Apple obligatoire : VM Linux ;
dépôt avec build Apple mais analyse générale : Linux pour l’analyse, Mac pour la compilation ;
dépôt avec signature, simulateur ou validation graphique : Mac distant dédié ;
tâche demandant des interfaces physiques ou un accès matériel spécifique : vérifier d’abord que la location distante répond réellement à cette contrainte.

Vous trouverez les modalités d’accès à un environnement Mac dans la page location de Mac mini distant. Pour les workflows qui nécessitent une interface graphique, la page accès VNC à distance aide à distinguer l’accès terminal de l’accès au bureau, ce qui est essentiel pour les simulateurs, les outils de design et certaines validations audio ou vidéo.

La validation avant exploitation continue

Ne considérez pas le déploiement comme terminé après une première réponse de l’agent. Faites une validation sur un dépôt représentatif, avec les mêmes scripts et restrictions que ceux de l’équipe.

[ ] Le VM peut être recréé à partir d’une procédure écrite et d’un stockage sauvegardé.
[ ] Le pare-feu bloque les ports internes et limite SSH aux adresses prévues.
[ ] LOCAL_BACKEND_API_KEY est stockée hors du dépôt, hors du frontend et hors des journaux.
[ ] Le répertoire visible par l’agent ne contient pas de secret non nécessaire.
[ ] Le mode direct ou Docker Sandbox a été choisi selon le niveau de risque du dépôt.
[ ] Une tâche longue continue après fermeture de la session SSH.
[ ] Le service revient après arrêt du processus et redémarrage de la machine.
[ ] Les événements temps réel restent actifs derrière le proxy inverse.
[ ] Les journaux sont consultables, limités et soumis à une rotation.
[ ] Le changement de backend ne mélange pas les chemins, branches ou conversations.
[ ] Un dépôt macOS a été envoyé vers le Mac distant uniquement lorsque ses outils l’exigent.
[ ] Un build réel a terminé sur la cible prévue, avec récupération du résultat et du journal.

Pour les équipes, ajoutez un test de concurrence avant d’autoriser plusieurs utilisateurs. Ne déduisez pas la capacité d’un VM à partir d’un seul lancement réussi : les conversations peuvent consommer différemment le processeur, la mémoire, le stockage et le réseau. La documentation Agent Server décrit des mécanismes d’isolation, de gestion des espaces de travail et de flux WebSocket, mais votre exploitation doit encore définir les quotas, les alertes et la politique de nettoyage adaptés à votre charge. (docs.openhands.dev)

Comparaison des architectures

Architecture	Niveau d’isolation	Persistance après SSH	Usage recommandé	Score de décision
Poste local, exécution directe	Faible	Faible	Prototype personnel et dépôt non sensible	2/5
VM Linux, exécution directe	Moyen	Élevée avec systemd	Développement contrôlé et tâches backend	4/5
VM Linux avec Docker Sandbox	Élevé si les volumes sont limités	Élevée	Équipe, dépôts partagés et exécution répétée	5/5
Mac distant dédié	Dépend de la configuration	Élevée avec supervision	Xcode, simulateurs, signature et outils Apple	4/5
VM Linux + Mac distant spécialisé	Élevé avec routage clair	Élevée	Équipes multiplateformes et chaînes de build séparées	5/5

Le poste local reste pratique pour une modification courte, mais il cumule veille, réseau domestique, fichiers personnels et droits excessifs. Le VM Linux devient le meilleur compromis dès que la tâche doit survivre à votre présence. Le Docker Sandbox mérite le meilleur score lorsque l’agent doit exécuter du code provenant de dépôts différents. Le Mac distant ne remplace pas cette base : il la complète lorsque la chaîne Apple impose une cible macOS.

À l’inverse, une machine locale peut rester préférable pour une tâche nécessitant un périphérique physique, un accès direct à un appareil de test ou une interaction graphique non transférable. Un VM Linux n’est pas non plus le bon choix pour compiler une application qui dépend réellement de Xcode. Dans ces deux cas, la décision doit suivre la contrainte technique plutôt que la recherche d’une architecture unique.

Après ce premier déploiement, documentez les étapes dans votre espace d’exploitation et conservez une procédure d’accès et de récupération adaptée à votre équipe. Votre installation actuelle — VM Linux seul ou VM complété par un Mac — doit être évaluée sur un dépôt réel, après un redémarrage, une tâche concurrente et une compilation complète.

Un poste personnel reste vulnérable au sommeil, aux interruptions réseau et à la présence de fichiers qui ne devraient jamais être accessibles à un agent. Un VM Linux peut aussi devenir insuffisant dès qu’Xcode, un simulateur ou une signature Apple entre dans le périmètre. Dans ce cas précis, louer un Mac auprès de SSHMac permet de conserver une cible macOS disponible sans transformer votre ordinateur quotidien en serveur permanent ; cela ne remplace toutefois pas une analyse préalable des secrets, des volumes et du processus de supervision.

FAQ

OpenHands Agent Canvas peut-il fonctionner sur un serveur distant accessible depuis un navigateur ?

Oui. Le guide officiel de déploiement prévoit un hôte Linux ou macOS toujours disponible, avec Agent Canvas, Agent Server et le backend d’automatisation lancés sur la même machine. Pour un premier essai, utilisez un tunnel SSH ou un réseau privé. Une publication publique ne devrait intervenir qu’après configuration de la clé API, du pare-feu, du proxy inverse et du TLS.

Comment conserver une tâche Agent Canvas après la fermeture de ma session SSH ?

La session SSH ne doit pas être le mécanisme de supervision. Pour un test rapide, lancez Agent Canvas dans tmux. Pour un service durable, créez une unité systemd avec redémarrage automatique, activation au démarrage et journalisation contrôlée. Vérifiez ensuite qu’une tâche, la connexion d’événements et l’interface reviennent après fermeture SSH et redémarrage du processus.

Quels ports faut-il ouvrir pour un Agent Server distant ?

Ne publiez pas directement les ports internes d’Agent Server, du backend d’automatisation ou du serveur statique. Dans le schéma officiel actuel, ces services restent liés à la machine, tandis que le proxy inverse expose uniquement le point d’entrée HTTPS. Le pare-feu doit limiter SSH à vos adresses autorisées et ne laisser passer que 80 et 443 si vous utilisez un domaine public.

Dans quels cas OpenHands doit-il utiliser un Mac distant ?

Un Mac distant devient pertinent lorsque la tâche exige Xcode, les simulateurs Apple, la signature, les frameworks macOS ou une chaîne de compilation native indisponible sous Linux. Pour l’analyse de code, les services Web, les tests backend et la plupart des tâches Git, un VM Linux isolé est généralement plus simple à maintenir. Le routage doit suivre le dépôt et ses outils, pas la préférence de l’utilisateur.

Quelle méthode choisir pour sécuriser l’accès public à Agent Canvas ?

Commencez par garder tous les services en écoute locale et validez l’installation avec un tunnel SSH. Pour l’accès public, activez le mode public afin que la clé ne soit pas intégrée à l’interface, imposez une clé API indépendante, placez nginx ou un proxy équivalent devant le point d’entrée, activez HTTPS et contrôlez les journaux, les connexions persistantes et le renouvellement du certificat.

Passez à un Mac distant prêt pour vos agents de développement

Mac mini M4 · Nœud de build Fonctionnement silencieux

Avec SSHMac, vous disposez d’un environnement Mac distant accessible en SSH pour exécuter vos tâches sans dépendre de votre ordinateur local. Conservez vos processus, fichiers et configurations sur une machine dédiée, même lorsque votre session SSH est interrompue.

$105.9

/ mois

Commencer