Français
Menu de la documentation

Documentation Agent Sandboxes · Premiers pas

Connecter un agent aux sandboxes par MCP

Mis à jour le · 6 min de lecture

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.

En bref
  • 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 ConnectSandbox et la CLI pethost ou curl.
  • À 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.

Claude Code

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 :

OutilCe qu’il fait
GetWorkspaceLes limites, les tailles et les prix de l’espace de travail, les noms de ses secrets et ses clés SSH.
ListSandboxesSes sandboxes, les plus récentes d’abord, par état, label ou nom.
CreateSandboxUne sandbox depuis un template, avec une réponse une fois qu’elle tourne.
GetSandboxUne sandbox : son état et pourquoi, ses paramètres, comment la joindre, sa consommation.
UpdateSandboxSon nom, sa taille, son cycle de vie, son trafic sortant, ses ports publics ou son environnement.
PauseSandboxLa met en pause, mémoire et processus gardés.
StopSandboxL’arrête, son disque gardé.
ResumeSandboxRedémarre une sandbox en pause ou arrêtée.
ForkSandboxLa copie, mémoire et processus compris, dans de nouvelles sandboxes.
DeleteSandboxLa supprime, avec sa mémoire et son disque, pour de bon.
ConnectSandboxLe serveur de la sandbox, un token pour lui et sa commande SSH.
CreateTemplateEnregistre le disque d’une sandbox comme template.
ListTemplatesNos 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 de SandboxRuntimeService par son nom, en JSON Connect, avec les noms de champs qu’utilisent les outils.
  • Sans shell, l’agent vous donne le panel_url de 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 (/mcp dans Claude Code).
  • Un outil répond WorkspaceChoice : le token atteint plusieurs espaces de travail de sandboxes. Dites à l’agent lequel ; il envoie son workspace à chaque appel.
  • L’agent cherche RunCommand : ce n’est pas un outil de ce serveur. Orientez-le vers ConnectSandbox et la CLI, ou installez le plugin, dont la skill le dit.
  • RESOURCE_EXHAUSTED avec LimitReached : 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.

Démarrer l’essai gratuit