Au 6 septembre 2026, les applications de bureau macOS, Windows et Linux d’Agent Canvas sont encore présentées comme des versions en préversion dans la documentation officielle d’installation. Symptôme : vous voulez essayer OpenHands rapidement, mais vous ne savez pas si l’application de bureau suffit ni où l’Agent exécutera réellement vos commandes.
Solution la plus rapide : choisissez la préversion de bureau ou npx pour un premier essai, Docker pour limiter clairement l’accès à un projet, et un backend distant pour la continuité, le partage ou des ressources séparées. L’application de bureau réduit les étapes de démarrage, mais ne constitue pas à elle seule une isolation de niveau serveur.

Cette installation d’OpenHands Agent Canvas s’adresse à trois profils : le développeur qui souhaite terminer une première tâche sans maîtriser Node.js et uv, l’utilisateur de Docker qui doit circonscrire les fichiers accessibles par l’Agent, et l’ingénieur de plateforme qui prépare un service persistant pour plusieurs personnes. Si vous cherchez seulement une démonstration sans accès à un dépôt sensible, vous pouvez aller directement à la partie sur la préversion de bureau. Si l’Agent doit modifier du code réel, lisez d’abord la section consacrée aux permissions.

Dernière mise à jour : 6 septembre 2026. Les informations ont été vérifiées à partir de la page officielle d’installation, de la documentation d’architecture et des instructions officielles pour les backends Docker et VM.

Le choix dépend d’abord de l’endroit où l’Agent travaille

Agent Canvas n’est pas, à lui seul, l’environnement d’exécution. Il s’agit de l’interface qui permet de lancer et de suivre des tâches ; le backend actif fournit le service, tandis que l’environnement d’exécution contient le dépôt, les outils, les secrets et les commandes réellement exécutées. Cette séparation est explicitement décrite dans la documentation d’architecture d’Agent Canvas.

Votre situation Interface Lieu d’exécution de l’Agent Accès principal Après l’arrêt
Première tâche sans dépôt sensible Application de bureau en préversion ou npx Votre ordinateur, selon le backend lancé Répertoire de travail choisi et permissions de votre compte La tâche et le processus peuvent s’arrêter avec l’application ou le terminal
Modification d’un projet local avec frontière claire Canvas local avec Docker Conteneur Docker Répertoire explicitement monté, plus les ressources exposées au conteneur Les fichiers du volume persistent si le volume est conservé ; les changements du conteneur éphémère peuvent disparaître
Travail reproductible sur une machine dédiée Canvas local ou distant avec Docker Hôte Docker ou machine virtuelle Volumes, réseau et secrets définis par l’administrateur Le backend peut être relancé si les données et la configuration sont persistantes
Tâches longues, accès depuis plusieurs appareils Canvas local relié à un backend distant VM ou hôte distant Dépôt, outils et ressources de la machine distante Le processus peut continuer indépendamment du terminal local, selon la configuration du backend
Équipe avec outils hétérogènes Interface partagée ou plusieurs Canvas Groupe de backends adaptés aux tâches Accès séparés par projet, équipe et environnement La reprise dépend de la persistance, des permissions et de l’état conservé côté serveur

Le point souvent manqué est le suivant : partager l’interface ne signifie pas partager le backend, et partager le backend ne signifie pas offrir le même environnement d’exécution. Une tâche Linux de génération de code, une tâche de montage vidéo et une tâche nécessitant des outils Apple ne doivent pas automatiquement être placées dans le même bassin de ressources.

Première étape : choisir la voie d’installation adaptée au premier essai

L’Agent Canvas Desktop App est intéressante si votre priorité est de réduire la friction initiale : ouverture de l’application, connexion au backend et lancement d’une tâche élémentaire. La contrepartie est que la préversion ne transforme pas automatiquement l’accès local en bac à sable. Si l’Agent démarre sur votre machine avec vos droits utilisateur, il peut potentiellement atteindre les fichiers et outils auxquels ce compte a accès.

La voie npx est généralement pertinente lorsque vous voulez éviter une installation persistante et tester la version publiée par le gestionnaire de paquets. Elle suppose néanmoins de disposer de l’environnement JavaScript attendu par la documentation officielle ; consultez donc les instructions Node.js relatives à l’installation par gestionnaire de paquets avant de lancer la commande fournie par OpenHands. La méthode npm convient mieux si vous souhaitez conserver une installation locale, contrôler son emplacement et gérer explicitement sa mise à jour.

Ne recopiez pas une commande trouvée dans un billet ancien sans comparer sa version avec la page officielle. Les commandes, les ports, les dépendances et le mode de connexion au backend peuvent évoluer ; la page d’installation reste la référence pour la syntaxe actuelle.

Attention : la présence d’une fenêtre graphique ne prouve ni l’isolation du système de fichiers, ni une séparation des secrets, ni une limitation réseau. Évaluez toujours le backend et l’environnement où les outils de l’Agent sont exécutés.

Pour valider un premier démarrage, ne lancez pas immédiatement une tâche destructive. Ouvrez Canvas, connectez le backend indiqué par la documentation, sélectionnez un petit répertoire de démonstration, puis demandez une opération observable et réversible : lire un fichier de texte, créer un fichier de sortie dans le même répertoire et afficher son contenu. La preuve de réussite doit comporter trois éléments : l’interface reçoit la tâche, l’Agent peut lire uniquement ce que vous avez prévu de lui donner, et le résultat est visible après l’exécution.

L’application de bureau nécessite-t-elle Node.js ?

La réponse dépend de la voie choisie, et non du seul nom « bureau ». Avec l’application de bureau précompilée, vous cherchez précisément à éviter une préparation complète de l’environnement de développement local ; avec npx ou npm, Node.js fait partie des prérequis à vérifier dans les instructions officielles. Ne supposez donc pas que l’application de bureau et le lancement par paquet offrent le même modèle de mise à jour.

Cette distinction est utile lorsque votre ordinateur sert aussi au développement audio, vidéo ou design. Une installation locale trop intrusive peut modifier le chemin des outils, les permissions ou la configuration du projet ; une application de préversion peut être plus rapide à retirer, mais elle ne protège pas automatiquement vos bibliothèques, vos fichiers média ou vos clés d’accès.

Deuxième étape : traiter l’accès aux fichiers comme une décision de sécurité

Une exécution locale directe est confortable parce que l’Agent voit l’environnement dans lequel vous travaillez déjà. C’est précisément son risque principal : les droits hérités du compte peuvent dépasser le seul dépôt concerné. Les fichiers de configuration, les clés SSH, les caches, les répertoires de travail voisins et les sockets accessibles à l’utilisateur ne deviennent pas magiquement invisibles parce que Canvas est ouvert dans une interface graphique.

Docker permet de dessiner une frontière plus explicite. Vous montez le répertoire du projet ou un volume dédié, vous choisissez où conserver la configuration, puis vous vérifiez les accès réseau et les capacités accordées au conteneur. Le principe de persistance par volume est décrit dans la documentation officielle des volumes Docker. Pour la procédure propre à Agent Canvas, utilisez le guide officiel du backend Docker.

Le conteneur n’est toutefois pas une garantie de séparation complète entre locataires. Une mauvaise configuration du montage, du socket Docker, du réseau ou des privilèges peut affaiblir la frontière. Les recommandations générales de sécurité du moteur Docker doivent être appliquées avant de confier un environnement partagé à plusieurs utilisateurs.

La décision conditionnelle

  • Si vous lisez, créez et supprimez uniquement des fichiers sans valeur dans un répertoire de test, choisissez la préversion de bureau ou npx pour aller vite.
  • Si l’Agent doit modifier un dépôt personnel mais que vous pouvez restaurer chaque fichier depuis Git, commencez en local, sans exposer de secrets inutiles, puis contrôlez les changements avant validation.
  • Si le dépôt contient des secrets, des données client, des fichiers de production ou des projets créatifs difficiles à reconstruire, revenez à Docker avec un répertoire monté explicitement et des secrets séparés.
  • Si plusieurs personnes doivent exécuter des tâches sur la même machine, choisissez un backend dédié ou une VM ; ne présentez pas un simple conteneur local comme un système complet de séparation des utilisateurs.
  • Si la tâche exige une chaîne d’outils macOS ou un périphérique physique, vérifiez l’environnement d’exécution avant de choisir Linux ou un backend Docker distant.

Troisième étape : rendre Docker reproductible au lieu de seulement fonctionnel

Docker est le meilleur compromis lorsque votre objectif est de reproduire un démarrage, un montage et une configuration. La séquence correcte ne consiste pas uniquement à démarrer un conteneur :

  1. Créez un répertoire de test distinct du dépôt de production et confirmez son propriétaire ainsi que ses permissions.
  2. Préparez un volume ou un chemin persistant pour la configuration et les données qu’Agent Canvas doit retrouver après un redémarrage.
  3. Montez uniquement le projet nécessaire ; évitez le montage global de votre dossier personnel et l’exposition du socket Docker sans justification.
  4. Configurez les variables d’environnement et les secrets séparément du code, puis contrôlez qu’ils ne sont pas écrits dans les journaux de tâche.
  5. Démarrez le backend en suivant la procédure officielle, puis connectez Canvas à l’adresse et au port réellement indiqués par ce backend.
  6. Demandez à l’Agent de lire un fichier autorisé et de tenter une lecture hors du répertoire monté avec un résultat attendu : refus, absence du chemin ou impossibilité documentée.
  7. Arrêtez le conteneur, redémarrez-le et vérifiez trois choses : la configuration est-elle retrouvée, les fichiers modifiés sont-ils toujours là, et une tâche interrompue peut-elle être reprise ?
  8. Conservez la procédure de lancement dans un fichier versionné sans y inscrire de jeton d’accès.

Cette validation est plus importante que la vitesse du premier démarrage. Un conteneur qui fonctionne une fois mais perd sa configuration à chaque arrêt n’est pas un environnement reproductible ; il s’agit seulement d’une démonstration temporaire.

Quand passer à un backend distant

Le Remote Backend devient pertinent lorsque l’ordinateur local ne doit plus porter l’exécution. C’est le cas d’une tâche qui doit survivre à la fermeture du terminal, à la mise en veille de l’ordinateur ou à une variation momentanée du réseau local. C’est également le cas lorsque plusieurs appareils doivent retrouver le même état de travail.

Dans cette architecture, Canvas reste le point de contrôle local, tandis que l’Agent, le dépôt, les outils et les données de tâche se trouvent sur une VM ou un hôte distant. Les instructions officielles pour une installation sur VM doivent être consultées pour la configuration du backend et son raccordement.

Une exposition publique ajoute plusieurs obligations : authentification forte, chiffrement TLS, filtrage des adresses autorisées, limitation des ports et surveillance des journaux. Ne publiez pas directement un port de développement sous prétexte que Canvas doit être accessible depuis l’extérieur. Pour une petite équipe, un accès privé au réseau de l’organisation est généralement plus facile à contrôler qu’un service ouvert sur Internet.

Le backend distant ne résout pas non plus la compatibilité par magie. Si une tâche dépend d’outils disponibles uniquement sur macOS, d’un périphérique audio, d’un accélérateur particulier ou d’une licence installée localement, vous devez réserver un environnement d’exécution compatible. Pour les besoins de développement Apple, vérifiez les conditions d’un environnement Mac distant avant de déplacer le backend.

Une application de bureau peut-elle se connecter au backend de l’équipe ?

Oui, à condition que l’édition utilisée accepte la connexion au backend concerné et que le service soit joignable avec les mécanismes d’authentification prévus. La bonne question n’est donc pas seulement « l’application se connecte-t-elle ? », mais aussi « quelles permissions l’utilisateur obtient-il une fois connecté ? ».

Séparez au minimum l’accès à l’interface, le droit de lancer une tâche, l’accès au dépôt et le droit de modifier l’environnement d’exécution. Une équipe peut partager un Canvas tout en attribuant des backends différents selon le projet. Cette organisation est préférable à un serveur unique auquel tous les utilisateurs accèdent avec les mêmes secrets.

Ce qu’il faut vérifier avant un usage d’équipe

Un déploiement d’équipe doit être évalué sur trois axes : permissions, reprise et reproduction. Les permissions déterminent qui peut voir un dépôt, démarrer une tâche ou lire les journaux. La reprise indique ce qui arrive à une tâche lorsqu’un navigateur est fermé, qu’un terminal disparaît ou que le réseau est interrompu. La reproduction mesure la capacité à retrouver les mêmes outils, versions et montages sur une nouvelle exécution.

Le programme de validation suivant évite de confondre partage d’écran et partage d’environnement :

  • créez deux comptes ou rôles de test avec des droits différents ;
  • lancez une tâche non destructive dans un dépôt de test ;
  • interrompez l’interface locale sans arrêter volontairement le backend ;
  • reconnectez-vous depuis un autre appareil et observez si l’état est retrouvé ;
  • vérifiez qu’un utilisateur non autorisé ne peut ni lire le dépôt, ni récupérer les secrets, ni modifier la configuration ;
  • reproduisez le lancement sur un second environnement et comparez les chemins montés, les variables et les outils disponibles.

Pour des tâches Linux génériques, un bassin de machines Linux peut suffire. Pour les tâches de compilation Apple, de design, d’audio ou de vidéo nécessitant une chaîne d’outils macOS, créez un groupe séparé. Une interface commune ne justifie pas de masquer ces contraintes techniques aux utilisateurs.

Rappel d’exploitation : un état de tâche persistant, un dépôt persistant et un environnement persistant sont trois choses différentes. Testez-les séparément, car la conservation du journal ne garantit pas la conservation du processus ni des fichiers modifiés.

Comparaison finale par scénario et note de décision

Les notes ci-dessous ne mesurent pas une performance brute ; elles indiquent l’adéquation au scénario décrit. Elles ne remplacent pas un essai sur votre dépôt, vos outils et vos règles de sécurité.

Solution Démarrage Limite des fichiers Continuité Partage d’équipe Note d’usage
Application de bureau en préversion 5/5 2/5 2/5 2/5 Premier essai sans données sensibles
npx ou npm local 4/5 2/5 2/5 2/5 Contrôle local et installation scriptable
Docker local 3/5 4/5 3/5 3/5 Projet monté avec frontière explicite
Docker sur hôte dédié 2/5 4/5 4/5 4/5 Environnement reproductible pour une équipe réduite
Backend sur VM ou hôte distant 2/5 4/5 5/5 5/5 Tâches longues, accès multi-appareils et ressources séparées

Lecture de la note : l’application de bureau gagne sur le démarrage, pas sur l’isolation. Docker gagne lorsque vous devez décider précisément quels fichiers sont visibles. Le backend distant devient supérieur dès que la continuité et l’accès partagé comptent davantage que la simplicité du poste local.

Contrôle avant validation Bureau ou npx Docker Backend distant
L’Agent peut-il atteindre uniquement le répertoire prévu ? À vérifier manuellement À tester par montage et refus À tester par permissions côté hôte
La configuration survit-elle à l’arrêt ? Dépend du mode de lancement Oui si le volume est persistant Oui si le stockage est persistant
Une tâche survit-elle à la fermeture du terminal ? Pas à présumer À vérifier sur l’hôte Objectif principal, à tester
Les secrets sont-ils séparés du dépôt ? Souvent à configurer Oui, avec une gestion dédiée Oui, avec contrôle serveur
L’environnement convient-il aux outils Apple ? Seulement si le poste les possède Pas automatiquement Seulement si le backend est sur un Mac compatible

Le choix le plus raisonnable pour votre prochaine tâche

Si votre solution actuelle est une exécution locale directe, elle reste séduisante pour sa simplicité, mais elle vous expose à trois défauts réels : les permissions du compte peuvent être trop larges, la mise en veille ou la fermeture du terminal peut interrompre la tâche, et la reproduction du même environnement pour un collègue demande souvent une configuration manuelle. Docker corrige surtout la frontière des fichiers, tandis qu’un backend distant corrige davantage la continuité et le partage.

Pour une tâche temporaire, un dépôt de test ou une vérification rapide, l’installation locale reste rationnelle. Pour une exécution persistante, une équipe ou un besoin de ressources séparées, louer un environnement Mac auprès de SSHMac peut offrir une expérience plus cohérente qu’un poste local laissé allumé : vous évitez de mobiliser votre machine principale, vous séparez mieux l’usage distant du poste quotidien et vous pouvez vérifier les conditions d’accès dans le centre d’aide SSHMac. Cette option ne remplace toutefois pas Docker lorsqu’une frontière stricte entre fichiers est indispensable, ni une infrastructure dédiée lorsqu’une charge lourde doit fonctionner en continu pendant une longue période.

Pour continuer, choisissez le chemin correspondant à votre scénario : la présentation de SSHMac pour évaluer un environnement distant, un guide d’installation local pour la première tâche, ou une validation de backend VM si votre équipe doit conserver les tâches après la fermeture des postes.