Sécurité

Comment déployer le bac à sable OpenHands en 2026 pour isoler les tâches de codage IA du Mac hôte ?

OpenHands doit être exécuté de préférence dans le bac à sable Docker documenté officiellement, avec pour seul dossier monté celui dont la tâche a réellement besoin. Cette voie convient aux modifications de code et aux scripts de dépôt dont le comportement n’est pas entièrement connu, à condition de ne pas traiter le conteneur comme une frontière de sécurité absolue ni de lui donner par défaut accès au socket Docker ou aux secrets de l’hôte.

Cet article s’adresse aux développeurs qui préparent leur première installation d’OpenHands sur Mac et veulent contrôler les montages avant de lancer un agent.
Il concerne aussi les petites équipes qui doivent séparer les projets, les identifiants et les accès réseau.
Les responsables de construction d’applications macOS y trouveront une méthode pour distinguer l’agent conteneurisé de l’environnement qui exécute les outils natifs.

Avant l’installation : choisir le périmètre d’exécution

La première décision concerne l’endroit où OpenHands exécutera les commandes demandées. Une exécution directement sur l’hôte et une exécution par le bac à sable Docker ne donnent pas les mêmes frontières d’accès. Pour un agent appelé à modifier un dépôt, lancer des tests ou exécuter des scripts fournis par ce dépôt, la voie conteneurisée constitue le point de départ le plus prudent. Elle ne garantit toutefois pas que les fichiers montés, les services accessibles ou les identifiants transmis soient protégés contre une action indésirable.

La présentation officielle des modes de bac à sable OpenHands aide à choisir le chemin d’exécution selon l’usage. La documentation actuelle du bac à sable Docker doit servir de référence pour sa configuration. En parallèle, la procédure d’installation locale officielle décrit le parcours d’installation à vérifier au moment du déploiement.

Il faut éviter de confondre cette documentation actuelle avec une procédure historique. Le document consacré à Docker Runtime et explicitement marqué V0 peut aider à comprendre d’anciennes configurations, mais son statut ne permet pas de considérer ses commandes ou options comme universelles. Avant de copier un exemple, vérifiez qu’il figure encore dans le parcours pris en charge et qu’il correspond à la version réellement installée.

Le choix dépend aussi du travail à accomplir. Pour une modification de code suivie de tests dans un dépôt isolé, le conteneur est généralement adapté. Pour une tâche qui doit compiler ou tester une application avec Xcode, le conteneur de l’agent ne doit pas être assimilé à un environnement macOS natif. Il faut planifier séparément l’endroit où l’agent travaille et celui où les outils Apple sont exécutés.

Avant le lancement : décider des accès nécessaires

Les erreurs de déploiement proviennent souvent d’un périmètre trop large, et pas seulement du choix entre exécution locale et conteneur. Un agent qui ne reçoit pas d’accès au dossier personnel ne peut pas en parcourir les fichiers par le seul fait que son interface s’ouvre sur le Mac. En revanche, un répertoire monté devient une ressource accessible selon les droits définis : s’il est monté en écriture, OpenHands peut y modifier ou supprimer des fichiers.

Les principales limites à anticiper sont les suivantes :

  • Le montage du projet : les changements de l’agent peuvent persister sur le Mac dans le répertoire partagé. « Exécuté dans un conteneur » ne signifie donc pas « incapable de toucher aux fichiers montés ».
  • Les identifiants : une clé de modèle, un jeton de dépôt ou une variable d’environnement fournie à l’agent peut être utilisée par les processus de la tâche. L’isolation du système de fichiers ne neutralise pas l’accès à un secret déjà transmis.
  • Le réseau : une tâche disposant d’un accès réseau peut contacter des services externes si la configuration le permet. Une frontière de fichiers ne remplace pas une politique réseau.
  • Le socket Docker : il s’agit d’une interface de contrôle du service Docker, pas d’un simple raccourci pour lire le dépôt. Sa présence modifie sensiblement le niveau de confiance à accorder au conteneur.
  • L’interface de gestion : un service accessible au-delà du Mac peut être consulté depuis un réseau plus large que prévu. Le mode de publication des ports doit donc être examiné, plutôt que repris sans vérification depuis un exemple de développement.

Une préparation défendable commence par un dossier propre à la tâche, sans fichiers personnels ni configuration globale inutile. Les documents de référence peuvent être conservés dans un emplacement séparé et montés en lecture seule lorsque la configuration le permet. La documentation Docker décrit les montages liés et leur option de lecture seule ; cette option limite l’écriture dans le chemin concerné, mais ne remplace ni la vérification des chemins effectivement montés ni la protection des secrets présents ailleurs.

Point de vigilance : le socket Docker doit être considéré comme une capacité d’administration du moteur. La documentation Docker avertit que la protection de l’accès au démon est un enjeu de sécurité ; ne partagez donc pas le socket avec l’agent tant que la tâche ne justifie pas précisément cet accès.

Pendant la préparation : établir le plan de déploiement

Avant d’exécuter la procédure officielle, consignez ce qu’OpenHands doit pouvoir lire, modifier et contacter. Cette démarche évite de confondre les quatre éléments en jeu : le conteneur de l’agent, le socket du moteur Docker, l’hôte macOS et l’environnement de compilation natif.

Élément Décision de déploiement Vérification avant la tâche
Agent OpenHands Choisir le mode conteneur documenté actuellement Confirmer le parcours et les options dans la documentation officielle
Répertoire de projet Ne monter que le dossier utile, en écriture seulement si nécessaire Contrôler le chemin source et les droits effectifs
Documents de référence Les séparer du projet ; privilégier un montage en lecture seule Vérifier qu’aucune écriture n’est attendue dans ces documents
Socket Docker Ne pas le rendre accessible par défaut Examiner la configuration réellement utilisée et justifier tout partage
Interface de gestion La réserver à l’interface réseau nécessaire Vérifier l’adresse d’écoute et la publication des ports
Outils macOS natifs Les placer dans un environnement de construction macOS distinct si requis Confirmer où Xcode et les outils Apple sont réellement installés

Cette comparaison sert à éviter deux raccourcis risqués : donner au conteneur un accès global « pour simplifier », ou supposer que le simple fait de lancer Docker suffit à isoler toutes les ressources du Mac. La configuration effective compte davantage que l’intitulé d’un mode d’exécution.

Au moment de déployer : suivre la procédure officielle

L’installation doit être réalisée à partir des instructions locales officielles correspondant au parcours actuel, et non d’une commande figée recopiée d’un article ancien. Les noms d’images, étiquettes, options de lancement et paramètres de montage évoluent ; en l’absence de vérification du document en vigueur, il serait imprudent de présenter une commande comme valable pour toute installation.

La documentation actuelle d’installation locale donne le point de départ. La documentation du bac à sable Docker précise les éléments propres à ce mode. Pour chaque paramètre, vérifiez s’il est nécessaire à l’installation, au lancement de l’interface ou à l’exécution des tâches : une option requise par un exemple complet n’est pas forcément nécessaire dans une configuration plus restreinte.

La publication d’un port mérite une attention particulière. Docker décrit que, lorsqu’une publication ne précise pas l’adresse de l’hôte, le service peut être exposé sur les interfaces réseau disponibles ; une publication liée à 127.0.0.1 limite l’accès à la boucle locale de l’hôte dans la configuration correspondante. Vérifiez les paramètres de votre lancement en vous appuyant sur la documentation Docker relative à la publication des ports et à l’adresse d’écoute. Ne rendez pas une interface accessible depuis le réseau public au seul motif que cela facilite un essai.

Le statut du socket mérite lui aussi une vérification dans la configuration effective, y compris les fichiers de lancement et les options ajoutées localement. Il ne faut pas déduire de la présence de Docker sur le Mac que le conteneur OpenHands peut nécessairement administrer Docker, ni supposer que cette capacité est indispensable. N’ajoutez pas le socket au conteneur sans besoin identifié.

Au premier démarrage : appliquer la décision de périmètre

Utilisez cette liste à cocher avant de confier un dépôt réel à OpenHands :

  • [ ] Si le dépôt peut exécuter des scripts inconnus ou modifier des fichiers, choisissez le bac à sable Docker documenté ; si ce mode ne répond pas au besoin, interrompez le déploiement et définissez une autre frontière d’exécution au lieu de lancer l’agent directement dans un espace personnel.
  • [ ] Si la tâche ne concerne qu’un projet, créez un dossier dédié et ne montez que ce dossier ; si les références doivent rester intactes, placez-les ailleurs et demandez un accès en lecture seule lorsque la configuration le permet.
  • [ ] Si le travail ne requiert pas de créer ou gérer des conteneurs, laissez le socket Docker inaccessible ; si un besoin précis l’impose, examinez les conséquences sur le démon avant d’accorder cette capacité.
  • [ ] Si seuls des essais locaux sont prévus, liez l’interface à une adresse locale ; si un accès réseau est indispensable, définissez explicitement qui peut joindre le service et contrôlez les paramètres de publication.
  • [ ] Si un jeton n’est utile qu’à une tâche, créez un accès limité à cette tâche et prévoyez sa révocation ; si ce niveau de limitation n’est pas possible, évitez de transmettre un identifiant durable.
  • [ ] Si la tâche exige Xcode ou un outil macOS natif, prévoyez un environnement macOS de construction séparé ; ne supposez pas que le conteneur de l’agent fournit les outils Apple.

Avant de passer à un dépôt sensible, lancez un essai avec un petit projet sans données confidentielles. Vérifiez que l’interface OpenHands est joignable depuis le périmètre prévu, que le mode conteneur est bien celui configuré et que les changements apparaissent uniquement dans le dossier attendu. Ce test ne prouve pas une sécurité absolue ; il confirme que les principaux paramètres de déploiement correspondent au plan établi.

Observez également le comportement après l’arrêt de la tâche : quels changements restent dans le dossier partagé, quels conteneurs ou processus sont encore présents, et quels identifiants ont été transmis ? Les fichiers montés peuvent conserver les modifications après la fin du processus de l’agent. Il faut donc examiner le contenu du dépôt et décider explicitement des changements à garder, plutôt que considérer l’arrêt du conteneur comme un retour automatique à l’état initial.

Pour les secrets : séparer les accès et prévoir leur retrait

Les secrets d’un service de modèle, les droits d’accès à un dépôt et les permissions du répertoire de travail répondent à des besoins différents. Les regrouper dans un profil durable ou les transmettre tous au conteneur « au cas où » élargit inutilement ce qu’une tâche peut utiliser. La règle de déploiement est de fournir le minimum nécessaire au travail défini, puis de retirer l’accès qui n’a plus de raison d’exister.

Pour un dépôt privé, privilégiez un identifiant dont les autorisations correspondent au dépôt concerné et à l’opération attendue. Les recommandations GitHub sur la protection des identifiants d’API expliquent les principes de protection des jetons ; sa documentation décrit aussi leur expiration et leur révocation. Appliquez ces consignes au jeton réellement utilisé, puis prévoyez sa révocation ou sa rotation dès la préparation de la tâche, et non après un incident.

Un jeton transmis à un processus de l’agent ne devient pas inoffensif parce que ce processus tourne dans un conteneur. Si le travail implique une API externe, vérifiez aussi quelles destinations réseau sont nécessaires. Une tâche de génération de code locale n’a pas automatiquement besoin des mêmes accès qu’une tâche chargée de publier des artefacts ou de modifier un dépôt distant.

Pour les constructions macOS : dissocier agent et compilation

OpenHands dans un conteneur et une construction native macOS sont deux rôles à planifier séparément. L’agent peut intervenir dans un espace de travail isolé, tandis qu’un environnement macOS distinct exécute les outils natifs requis par l’application. Cette séparation aide à limiter les droits de l’agent sans prétendre que le conteneur lui-même constitue une machine macOS ou remplace Xcode.

La documentation Apple sur App Sandbox présente un mécanisme de sécurité destiné aux applications et aux capacités qui leur sont autorisées. Elle ne permet pas de conclure que cette protection s’applique automatiquement au conteneur OpenHands, ni de présenter sandbox-exec comme la solution universelle au déploiement de l’agent. Il faut donc éviter de mélanger les modèles de sécurité : le bac à sable Docker contrôle un périmètre d’exécution configuré autour du conteneur, tandis que les mécanismes Apple relèvent de la sécurité des applications macOS.

Lorsque le besoin de compilation native apparaît, il est possible de traiter le code dans le bac à sable, puis de confier la construction à un environnement macOS adapté selon une procédure maîtrisée. Cela ne transforme pas cet environnement en garantie de sécurité du conteneur ; il s’agit d’une séparation des responsabilités. Pour préparer cet usage, consultez les informations d’aide de KuzCloud et la console KuzCloud, puis vérifiez les conditions applicables à l’environnement envisagé. Les règles de traitement des données sont également à examiner dans la politique de confidentialité de KuzCloud.

Après la tâche : fermer l’environnement proprement

La fin du travail doit inclure le traitement des fichiers et des accès, pas seulement l’arrêt de l’interface. Conservez ou examinez les modifications voulues dans le dossier de projet, puis supprimez les conteneurs ou ressources de tâche que vous n’avez plus besoin de garder conformément à la procédure utilisée. Retirez les variables temporaires et révoquez les jetons devenus inutiles. Si un environnement est conservé pour un prochain essai, ne le considérez pas automatiquement comme fiable : contrôlez à nouveau les montages, les ports publiés et les capacités accordées.

Le bac à sable Docker est un choix de déploiement utile lorsque l’objectif est d’encadrer un agent de codage, mais il ne dispense pas de limiter les ressources exposées. Une exécution locale directe peut être plus simple pour un dépôt maîtrisé et des opérations sans accès sensible, mais elle rapproche davantage l’agent des ressources de l’hôte. À l’inverse, un environnement macOS dédié peut être pertinent pour Xcode ou d’autres outils natifs, sans remplacer la nécessité de gérer les permissions et les secrets.

Le bon arbitrage consiste à ne pas acheter de complexité de construction native pour une tâche qui n’en a pas besoin, et à ne pas confier une tâche Xcode à un conteneur qui ne fournit pas ces outils. Si un environnement macOS temporaire est requis pour construire ou tester une application, KuzCloud peut être étudié comme option distincte pour cette étape native ; il ne constitue pas une garantie supplémentaire pour le bac à sable OpenHands. Les quatre questions de la FAQ ci-dessous permettent de vérifier les frontières avant la première tâche.

Questions fréquentes

Comment exécuter OpenHands sur macOS avec un bac à sable Docker ?

La procédure dépend du parcours actuellement documenté par OpenHands. Commencez par l’installation locale officielle, puis suivez les instructions Docker à jour au lieu de reprendre automatiquement une configuration marquée V0. Préparez un dossier de projet séparé et vérifiez la commande ou la configuration effective avant de lancer une tâche contenant des données privées.

Quels fichiers du Mac OpenHands peut-il atteindre ?

L’accès dépend des chemins et des capacités exposés au conteneur. Un dossier monté en écriture peut être modifié par l’agent, même si le reste du Mac n’est pas monté. N’ajoutez pas le dossier personnel ou des emplacements sans rapport avec la tâche ; séparez les documents de référence et vérifiez les options de lecture seule ainsi que les chemins réellement visibles.

Pourquoi un conteneur OpenHands utiliserait-il le socket Docker ?

Le socket permet au processus qui y accède de communiquer avec le service Docker. Certaines configurations ou tâches de gestion de conteneurs peuvent le demander, mais le simple besoin d’éditer et de tester du code dans un projet ne justifie pas à lui seul de le partager. Examinez la configuration effective et les conséquences avant de donner au conteneur cette capacité.

Comment limiter OpenHands au projet en cours ?

Créez un répertoire dédié à la tâche et indiquez uniquement ce chemin comme source du montage prévu par la configuration officielle. N’utilisez pas le dossier personnel entier comme espace de travail. Pour les références qui ne doivent pas être modifiées, séparez-les du projet et choisissez un montage en lecture seule si les options documentées le permettent ; vérifiez ensuite les accès avant le travail réel.

Exécutez vos tâches de codage IA sur un Mac dédié dans le cloud

Avec KuzCloud, déplacez l’exécution sur un Mac mini M4 physique dédié, à l’écart de votre Mac personnel.

Configurez votre environnement de développement avec un accès root complet et gardez vos outils et fichiers locaux hors de portée des tâches exécutées à distance.