Utiliser un agent IA avec une sandbox

Une sandbox sert à donner à un agent IA une machine jetable et isolée : il peut installer des paquets, lancer Docker ou exécuter du code sans risque pour votre ordinateur. Trois façons de travailler :

1. L'agent tourne dans la sandbox : vous vous connectez et lancez claude, codex, etc.
2. L'agent tourne sur votre machine et exécute ses commandes dans la sandbox via ssh yorkhost.sh '…'.
3. L'assistant n'a pas de SSH (Claude.ai, ChatGPT…) : relié à votre compte par MCP, il travaille dans la sandbox avec sandbox_exec et les outils de fichiers.

1. Lancer un agent dans la sandbox

Connectez-vous (ssh yorkhost.sh), placez-vous dans votre projet, puis lancez l'agent de votre choix :

Agent	Commande
Claude Code	claude
OpenAI Codex	codex
OpenCode	opencode
Cursor CLI	cursor-agent
Gemini CLI	gemini

Au premier lancement, chaque agent vous demande de vous connecter à votre propre compte chez son éditeur (Anthropic, OpenAI, Cursor, Google…) : suivez l'invite, qui affiche en général un lien à ouvrir dans le navigateur de votre ordinateur. Vous pouvez aussi fournir une clé API par variable d'environnement, par exemple :

export ANTHROPIC_API_KEY=…   # Claude Code
export OPENAI_API_KEY=…      # Codex
export GEMINI_API_KEY=…      # Gemini CLI

L'abonnement ou la consommation de l'agent restent facturés par son éditeur : YorkHost fournit la machine, pas le modèle.

Ne plus retaper vos clés

Enregistrez vos clés une fois comme secrets de votre compte YorkHost (ANTHROPIC_API_KEY, OPENAI_API_KEY, GITHUB_TOKEN…) : elles sont injectées automatiquement dans chaque nouvelle sandbox créée depuis votre compte. Voir Secrets du compte. Les sandboxes créées avec ssh yorkhost.sh, sans compte, ne les reçoivent jamais.

Vos identifiants sont dans la VM

Les jetons de connexion et clés API que vous saisissez sont stockés dans la sandbox (et copiés sur le VPS si vous la gardez, car ils sont dans /home/agent). Préférez une clé dédiée, avec un plafond de dépense, que vous révoquerez après l'essai. Ne donnez jamais à l'agent plus d'accès que nécessaire (dépôts Git, clés cloud…).

Ce que l'agent sait déjà

Le dossier /home/agent contient un fichier AGENTS.md (lié en CLAUDE.md et GEMINI.md) que Claude Code, Codex, OpenCode, Cursor CLI et Gemini CLI lisent au démarrage. Il leur rappelle d'écouter sur 0.0.0.0 pour la preview, quels ports sortants sont ouverts, la durée de vie de la sandbox et comment la garder. Un agent qui découvre YorkHost depuis ailleurs trouve le même résumé sur yorkhost.sh/llms.txt.

Récupérer votre code

Clonez vos dépôts directement dans la sandbox (git clone, gh repo clone après gh auth login), ou envoyez vos fichiers avec scp / rsync. Git en HTTPS et en SSH fonctionne.

Garder l'agent actif

Lancez l'agent dans tmux : si votre connexion coupe, il continue de travailler et vous le retrouvez avec tmux attach. Pensez à l'heure d'arrêt (60 minutes après la création, 2 h pour une sandbox créée depuis votre compte) : poussez régulièrement votre travail sur Git, téléchargez-le avec ssh -T export@yorkhost.sh > sandbox.tar.gz, ou gardez la sandbox en VPS pour continuer.

Tester le résultat

Demandez à l'agent de démarrer l'application sur 0.0.0.0:8080 (ou un autre port de preview) : vous l'ouvrez aussitôt dans votre navigateur sur https://<id>-8080.yorkhost.sh.

2. Piloter la sandbox depuis un agent local

Un agent qui tourne sur votre ordinateur (Claude Code, Cursor, un script…) peut utiliser la sandbox comme environnement d'exécution isolé : chaque commande passée à ssh yorkhost.sh s'exécute dans la sandbox, avec son code de sortie.

ssh -o StrictHostKeyChecking=accept-new yorkhost.sh 'git clone https://github.com/moi/projet && cd projet && npm ci && npm test'

Quelques consignes utiles à donner à votre agent :

• Obtenir l'état, l'adresse de preview et les échéances en JSON : ssh status@yorkhost.sh.
• Utiliser l'identifiant de la sandbox (ssh sbx…@yorkhost.sh) une fois qu'elle existe, pour toujours viser la même.
• Ne jamais lancer ssh destroy@yorkhost.sh ni commander quoi que ce soit sans votre accord.

Un agent relié à votre compte YorkHost

Si votre agent est connecté à votre compte YorkHost (serveur MCP ou clé API), il peut aussi créer des sandboxes (2 h d'essai), lister leurs URLs et proposer de les garder en VPS, toujours avec votre validation avant toute commande. Enregistrez votre clé SSH sur le compte (clés SSH du compte) pour rejoindre avec ssh <id>@yorkhost.sh les sandboxes qu'il crée. Voir API et MCP.

3. Un assistant web, sans SSH

Claude.ai, ChatGPT et les autres assistants connectés par le web ne peuvent pas ouvrir de session SSH. Reliez-les à votre compte avec le serveur MCP, en cochant les permissions « Voir » et « Créer et supprimer des sandboxes agents » : ils créent alors une sandbox (create_sandbox) et y travaillent avec quatre outils.

Outil	Rôle
sandbox_exec	Exécute une commande shell et renvoie sa sortie et son code de sortie.
sandbox_list_files	Liste un dossier.
sandbox_read_file	Lit un fichier.
sandbox_write_file	Crée ou remplace un fichier.

Tout s'exécute sous l'utilisateur agent, dans une sandbox en cours (pas Windows), sur des chemins sous /home/agent ou /tmp. Chaque commande dure 60 s par défaut et 300 s au plus ; les sorties sont coupées au-delà de 256 Kio et les fichiers limités à 1 Mio. Un serveur de dev se lance en arrière-plan avec ses sorties redirigées (nohup npm run dev > /tmp/dev.log 2>&1 &), puis se teste sur la preview. Détails et limites : API et MCP.

Bonnes pratiques

• Une sandbox par tâche : une clé SSH n'a qu'une sandbox à la fois. Supprimez-la (ssh destroy@yorkhost.sh) avant d'en demander une nouvelle.
• Rien d'important uniquement dans la sandbox : elle est supprimée avec ses fichiers au bout de 24 h, et n'est pas sauvegardée. Poussez sur Git ou téléchargez /home/agent avec export avant l'arrêt.
• Réseau sortant limité : l'agent peut télécharger (web, Git, registres npm/PyPI/Docker), mais pas joindre une base de données distante ou un serveur mail. Détails dans Limites et sécurité.