Documentation Agent Sandboxes · Premiers pas
Connecter un agent aux sandboxes par MCP
Des sandboxes comme outils de votre agent : ajoutez le serveur MCP de Pethost Agent Sandboxes, https://mcp.pethost.dev/sandboxes, à Claude Code, Codex, Cursor ou Claude, connectez-vous dans votre navigateur, et l’agent crée, duplique, met en pause et supprime lui-même des sandboxes.
- Une seule adresse :
https://mcp.pethost.dev/sandboxes, en HTTP streamable, avec connexion par OAuth. Aucune clé à coller. - Vous choisissez l’espace de travail : la page de connexion propose vos espaces de travail de sandboxes, et le token de l’agent n’atteint que ceux que vous cochez.
- 13 outils pour l’espace de travail et le registre de chaque sandbox. Les commandes et les fichiers vont au serveur de la sandbox, que l’agent atteint avec
ConnectSandboxet la CLIpethostoucurl. - À part d’App Platform : un connecteur à lui, si bien qu’un agent configuré pour l’un ne voit jamais les outils de l’autre.
Step 1: Ajoutez le serveur à Claude Code
claude mcp add --transport http pethost-sandboxes https://mcp.pethost.dev/sandboxes
Ou installez le plugin, qui apporte le serveur et une skill qui dit à Claude quand et comment utiliser les sandboxes : claude plugin marketplace add pethost-dev/plugin, puis claude plugin install pethost-sandboxes@pethost.
Step 2: Connectez-vous
Dans Claude Code, lancez /mcp, choisissez pethost-sandboxes et authentifiez-vous. Votre navigateur ouvre la page d’autorisation de Pethost : connectez-vous, choisissez l’espace de travail de sandboxes que l’agent peut utiliser, et cliquez sur Connecter.
Step 3: Demandez quelque chose qui a besoin d’un ordinateur
« Crée une sandbox, clone ce dépôt et lance ses tests. » L’agent lit l’espace de travail, crée une sandbox depuis base et y travaille.
Vous dites : Crée une sandbox, clone https://github.com/pallets/click et lance ses tests.
- CreateSandbox {"name": "click-tests"}
- ConnectSandbox {"sandbox_id": "lelb0x9iq6pvk7t8", "ttl_seconds": 3600}
- Bash curl …/SandboxRuntimeService/RunCommand: git clone -q https://github.com/pallets/click
- Bash curl …/SandboxRuntimeService/RunCommand: python3 -m venv .venv && .venv/bin/pip install -q -e . pytest && .venv/bin/python -m pytest -q
L’agent répond : Tous les tests de click passent dans une nouvelle sandbox : 2628 passed, 24 skipped, 1 xfailed, 0 failed (code de sortie de pytest : 0). … La sandbox se mettra en pause après 5 minutes d’inactivité et s’arrêtera après 30, mais elle n’est pas supprimée automatiquement. Je la supprime, ou tu la gardes pour la suite ?
Codex
Le plugin, pour la CLI et l’application de bureau, apporte le serveur et la skill : codex plugin marketplace add pethost-dev/plugin, puis codex plugin add pethost-sandboxes@pethost. Vous vous connectez dans votre navigateur, comme avec Claude Code, et y choisissez l’espace de travail.
Cursor
Ajoutez le serveur à ~/.cursor/mcp.json, ou à .cursor/mcp.json dans un projet, puis activez-le dans les paramètres MCP de Cursor, qui lancent la connexion :
{
"mcpServers": {
"pethost-sandboxes": { "url": "https://mcp.pethost.dev/sandboxes" }
}
}
Claude sur le web et sur ordinateur
Dans les paramètres de Claude, ouvrez Connecteurs, ajoutez un connecteur personnalisé et donnez-lui l’adresse https://mcp.pethost.dev/sandboxes. Claude ouvre la page de connexion ; activez ensuite le connecteur dans une conversation.
Tout autre agent
Tout client MCP qui parle HTTP streamable et se connecte par OAuth prend l’adresse https://mcp.pethost.dev/sandboxes. Hermes Agent : hermes mcp add pethost-sandboxes --url https://mcp.pethost.dev/sandboxes --auth oauth. La skill, pour un agent qui lit les skills : npx skills add pethost-dev/plugin --skill pethost-sandboxes. Un agent qui n’a que le serveur lit plutôt ses instructions, qui disent par où commencer.
Les outils
Les outils du serveur sont les appels de SandboxService, la moitié de l’API qui revient à la console, chacun avec les mêmes nom, champs et réponses que dans la référence de l’API :
| Outil | Ce qu’il fait |
|---|---|
GetWorkspace | Les limites, les tailles et les prix de l’espace de travail, les noms de ses secrets et ses clés SSH. |
ListSandboxes | Ses sandboxes, les plus récentes d’abord, par état, label ou nom. |
CreateSandbox | Une sandbox depuis un template, avec une réponse une fois qu’elle tourne. |
GetSandbox | Une sandbox : son état et pourquoi, ses paramètres, comment la joindre, sa consommation. |
UpdateSandbox | Son nom, sa taille, son cycle de vie, son trafic sortant, ses ports publics ou son environnement. |
PauseSandbox | La met en pause, mémoire et processus gardés. |
StopSandbox | L’arrête, son disque gardé. |
ResumeSandbox | Redémarre une sandbox en pause ou arrêtée. |
ForkSandbox | La copie, mémoire et processus compris, dans de nouvelles sandboxes. |
DeleteSandbox | La supprime, avec sa mémoire et son disque, pour de bon. |
ConnectSandbox | Le serveur de la sandbox, un token pour lui et sa commande SSH. |
CreateTemplate | Enregistre le disque d’une sandbox comme template. |
ListTemplates | Nos templates et ceux de l’espace de travail. |
Commandes et fichiers : sur le serveur de la sandbox
Ce qui tourne dans une sandbox, ses commandes, ses fichiers, son bureau, ses liens et ses agents de code, reçoit sa réponse du serveur où tourne la sandbox, jamais de la console. Le serveur MCP de mcp.pethost.dev/sandboxes ne liste donc pas de RunCommand : l’agent appelle ConnectSandbox, qui répond avec l’url du serveur, un token pour cette seule sandbox et sa ssh_command, puis y travaille lui-même :
- Avec la CLI
pethost, là où l’agent a un shell :pethost sandbox run <id> -- npm test,pethost sandbox cp ./app <id>:app,pethost sandbox shell <id>. - Avec
curl, n’importe quel appel deSandboxRuntimeServicepar son nom, en JSON Connect, avec les noms de champs qu’utilisent les outils. - Sans shell, l’agent vous donne le
panel_urlde la sandbox, où se trouvent son terminal et son bureau, une fois connecté.
curl -s "$URL/pethost.sandboxes.v1.SandboxRuntimeService/RunCommand" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"sandbox_id": "'"$ID"'", "command": "npm test"}'
Le token donne root dans cette sandbox : les instructions du serveur et la skill disent à l’agent de le garder dans une variable du shell et de ne jamais l’afficher dans la conversation.
Un token pour ce seul serveur
La connexion donne à l’agent un token d’API Pethost dont l’audience est ce serveur : il marche sur mcp.pethost.dev/sandboxes et sur l’API des sandboxes, et il est refusé par le serveur MCP d’App Platform, comme le token d’App Platform est refusé ici. Il n’atteint que les espaces de travail que vous avez cochés. Les Paramètres de votre compte le listent sous le nom de l’agent, avec ce qu’il atteint, et le révoquent.
Pourquoi c’est un connecteur à part
App Platform et Agent Sandboxes sont deux produits avec des outils différents et un lecteur différent en tête : un agent qui déploie vos applications, et un agent qui a besoin d’ordinateurs pour exécuter du code. Chacun a son propre serveur, son nom, son icône, ses outils et ses tokens : un agent configuré pour l’un ne lit donc jamais les outils de l’autre, et ne les confond pas. Un compte qui a les deux ajoute les deux : celui d’App Platform est https://mcp.pethost.dev/mcp.
Quand ça ne marche pas
- La page de connexion ne propose aucun espace de travail : elle ne propose que des espaces de travail de sandboxes. Créez-en d’abord un dans la console, en choisissant Agent Sandboxes.
- L’agent dit qu’il n’est pas connecté, ou ses appels répondent 401 : le token a été révoqué, ou l’agent s’est connecté au serveur d’App Platform. Reconnectez-vous depuis l’agent (
/mcpdans Claude Code). - Un outil répond
WorkspaceChoice: le token atteint plusieurs espaces de travail de sandboxes. Dites à l’agent lequel ; il envoie sonworkspaceà chaque appel. - L’agent cherche
RunCommand: ce n’est pas un outil de ce serveur. Orientez-le versConnectSandboxet la CLI, ou installez le plugin, dont la skill le dit. RESOURCE_EXHAUSTEDavecLimitReached: les vCPU de l’espace de travail sont occupés par ses sandboxes actives et en pause. Demandez à l’agent de supprimer celles dont il n’a plus besoin.
Questions
Quelle est l’adresse du serveur MCP ?
https://mcp.pethost.dev/sandboxes, en HTTP streamable, avec connexion par OAuth dans votre navigateur.
Quels agents marchent avec Pethost Agent Sandboxes ?
Tout agent qui accepte un serveur MCP distant : Claude Code, Codex, Cursor, Claude sur le web et sur ordinateur, Hermes Agent et d’autres. Claude Code et Codex peuvent installer le plugin, qui ajoute une skill.
L’agent peut-il lancer des commandes dans une sandbox par MCP ?
Par le serveur de la sandbox : ConnectSandbox donne son adresse et un token, et l’agent lance des commandes avec la CLI pethost ou curl. Le serveur MCP lui-même crée, modifie, met en pause, duplique et supprime des sandboxes.
L’agent reçoit-il mes clés d’API ?
Non. Il reçoit un token pour les espaces de travail que vous cochez. Les clés des modèles et des services sont des secrets de l’espace de travail, qu’aucune sandbox ni aucune réponse d’outil ne détient jamais.
Est-ce le même serveur que celui de Pethost App Platform ?
Non : celui d’App Platform est https://mcp.pethost.dev/mcp. Chacun a ses propres outils et tokens.
Essayez Pethost Agent Sandboxes
Un essai gratuit de 7 jours avec 1 $ de consommation et 4 vCPU, avec une carte. Ensuite, une offre dès 20 $ par mois, qui inclut autant de consommation.