Claude Platform Docs
Managed AgentsSandboxes auto-hébergées

Sandboxes auto-hébergés

Exécutez les sessions Claude Managed Agents dans des sandboxes auto-hébergés, en conservant l'exécution des outils, les fichiers et le trafic réseau sortant dans votre propre infrastructure.

Les sandboxes auto-hébergés déplacent l'exécution des outils de l'agent depuis les sandboxes cloud gérés par Anthropic vers une infrastructure que vous contrôlez, tandis qu'Anthropic continue d'exécuter l'agent. Pour comprendre ce que cela implique et décider si cela convient à votre agent, consultez Choisir un environnement d'agent.

Fonctionnement

Un environnement self_hosted agit comme une file de travail. Vous exécutez un environment worker (worker d'environnement), un processus sur votre propre infrastructure qui dessert cette file :

  1. Vous créez une session qui cible l'environnement. Anthropic place la session dans la file en tant qu'élément de travail.
  2. Votre worker réclame l'élément de travail et télécharge les skills de l'agent ainsi que les memory stores de la session.
  3. Claude s'exécute du côté d'Anthropic et demande des appels d'outils. Votre worker exécute chaque appel localement et renvoie le résultat.

Les entrées et sorties des outils transitent toujours par le plan de contrôle d'Anthropic, afin que le modèle puisse voir les résultats et déterminer la suite. Anthropic stocke les skills et les memory stores. Votre sandbox en conserve une copie pour la session. Consultez Modèle de sécurité pour connaître la frontière complète des flux de données.

Les sandboxes auto-hébergés prennent en charge tous les modèles Claude disponibles dans Managed Agents. Le modèle est configuré sur l'agent, et non sur l'environnement.

La CLI ant et les SDK Python, TypeScript et Go fournissent des workers préconstruits. Des fournisseurs de sandboxes tels que Cloudflare, Daytona et Modal publient également leurs propres guides de plateforme.

Démarrage rapide

Ce démarrage rapide exécute un worker toujours actif avec la CLI ant, lui envoie une session et confirme que les appels d'outils de l'agent se sont exécutés sur votre hôte.

Prérequis

  • Un agent : si vous n'en avez pas, suivez d'abord Premiers pas avec Claude Managed Agents et notez l'ID de l'agent.
  • Un hôte Linux : l'hôte doit disposer de /bin/bash à ce chemin exact. Le worker n'a besoin que de HTTPS sortant.
  • Une clé API Claude : vous l'utilisez depuis votre propre machine pour créer des sessions et lire les statistiques de la file. Ne la placez pas sur l'hôte du worker, où les appels d'outils de l'agent pourraient la lire.
  • La CLI ant ou le SDK sur votre propre machine : les étapes de statistiques et de session de ce démarrage rapide s'exécutent là, et non sur l'hôte du worker. Installez la CLI de la même manière que l'étape d'installation le fait pour le worker, ou installez le SDK.

Exécuter votre première session

  1. Créer un environnement auto-hébergé

    Dans la Claude Console, accédez à la page Environments (platform.claude.com/environments), cliquez sur Create environment, puis sous Hosting, sélectionnez Self-hosted.

    Ou via l'API :

    ant apply environment.yaml
    environment.yaml
    # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: self-hosted
config:
  type: self_hosted

  2. Générer une clé d'environnement

    Dans la Console, ouvrez l'environnement et cliquez sur Generate environment key. La clé d'environnement authentifie le worker auprès de sa file. Vous ne pouvez en générer une que dans la Console, même pour un environnement créé via l'API.

    Exportez l'ID et la clé de l'environnement sur l'hôte du worker :

    export ANTHROPIC_ENVIRONMENT_KEY="sk-ant-oat01-..."
export ANTHROPIC_ENVIRONMENT_ID="env_..."

  3. Installer la CLI ant

    Exécutez ceci sur l'hôte du worker.

    Pour les environnements Linux, téléchargez directement le binaire de la version.

    VERSION=1.42.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
  x86_64) ARCH=amd64 ;;
  aarch64) ARCH=arm64 ;;
esac
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin ant

    Vous trouverez toutes les versions sur la page des versions GitHub.

  4. Démarrer le worker

    Créez le répertoire de travail, puis démarrez le worker. --workdir utilise par défaut le répertoire courant ; passez donc /workspace pour correspondre à la valeur par défaut du système.

    sudo mkdir -p /workspace && sudo chown "$USER" /workspace
ant beta:worker poll --workdir /workspace

    Le worker lit les deux variables que vous avez exportées et interroge la file jusqu'à ce que vous l'arrêtiez.

  5. Vérifier que le worker est connecté

    Sur votre propre machine, définissez ANTHROPIC_API_KEY sur votre clé API Claude (et non sur la clé d'environnement) et environment_id sur l'ID de l'environnement. Vérifiez que workers_polling vaut au moins 1 :

    client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(environment_id)
print(f"workers_polling={stats.workers_polling}")

    Si workers_polling reste à 0, consultez Dépannage.

  6. Démarrer une session

    Définissez agent_id sur l'ID de votre agent. Créez une session qui cible l'environnement, puis envoyez-lui une tâche :

    session = client.beta.sessions.create(
    agent=agent_id,
    environment_id=environment_id,
)

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {
                    "type": "text",
                    "text": 'Write the output of "uname -a" to hello.txt in your working directory.',
                },
            ],
        },
    ],
)

    La session attend dans la file de l'environnement jusqu'à ce qu'un worker la réclame. Si aucun worker n'est connecté, la session reste en file d'attente au lieu d'échouer.

  7. Confirmer que les outils se sont exécutés sur votre hôte

    Sur l'hôte du worker, lisez le fichier écrit par l'agent :

    cat /workspace/hello.txt

    Le fichier décrit le noyau de votre propre hôte ; les appels d'outils de l'agent s'y sont donc bien exécutés. Pour suivre le travail de l'agent en temps réel, consultez Flux d'événements de session.

Ressources de session

Les sandboxes auto-hébergés prennent en charge uniquement les ressources memory_store. Une session sur un environnement auto-hébergé qui inclut une ressource file ou github_repository est rejetée avec une erreur 400 :

Environment env_... is a self-hosted environment. `resources` are not supported with self-hosted environments.

Les déploiements qui ciblent un environnement auto-hébergé suivent la même règle. Pour fournir à une session ses propres fichiers d'entrée, consultez Préparer des fichiers pour une session.

Sandboxes auto-hébergés et tunnels MCP

L'auto-hébergement contrôle l'endroit où le code de l'agent s'exécute. Les tunnels MCP contrôlent la manière dont Anthropic atteint les serveurs MCP de votre réseau. Les deux sont indépendants :

  • Une session dans les sandboxes cloud d'Anthropic peut atteindre des serveurs MCP privés via un tunnel. Par exemple, un serveur MCP privé peut se trouver devant une base de données ou une API interne derrière votre pare-feu.
  • Une session auto-hébergée peut utiliser des serveurs MCP tunnelisés ou publics.

Utilisez les deux lorsque vous souhaitez que l'exécution et l'accès aux outils restent à l'intérieur de votre périmètre. Pour vous passer du tunnel, encapsulez le serveur MCP sous forme d'outils personnalisés que votre worker dessert.

Guides de plateforme

Ces pages décrivent comment construire un worker sur n'importe quelle plateforme de sandboxing. Des guides spécifiques à certaines plateformes sont également disponibles :

Étapes suivantes

Déployer des workers

Exécutez le worker du SDK, déclenchez des workers à partir de webhooks ou attribuez à chaque session son propre sandbox.

Memory stores

Préparez l'hôte, configurez la synchronisation et gérez les stores en lecture seule et les conflits.

Outils personnalisés et serveurs MCP

Servez vos propres outils depuis le worker, y compris des outils provenant d'un serveur MCP à l'intérieur de votre réseau.

Surveiller et dépanner

Lisez la profondeur de la file, arrêtez proprement les sessions et les workers, et corrigez les défaillances courantes.

Référence du worker

Options de la CLI, variables d'environnement, chemins du système de fichiers et options des helpers du SDK.

Modèle de sécurité

Modèle de responsabilité partagée pour les environnements de sandboxes auto-hébergés.

Was this page helpful?