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

Exécuter une sandbox par session

Donnez à chaque session sa propre sandbox auto-hébergée avec le chart Helm sur Kubernetes, un script de lancement ou le poller du SDK.

Dans le modèle d’une sandbox par session, chaque session s’exécute dans une nouvelle sandbox, qui peut avoir son propre système de fichiers, ses propres limites de ressources et ses propres contrôles réseau. Pour le comparer aux autres modèles, consultez Choisir un modèle de déploiement.

Vous pouvez le mettre en place de trois façons :

  • Chart Helm sur Kubernetes : le « dispatcher » (répartiteur) d’Anthropic réclame le travail et démarre un pod pour chaque session sur votre cluster.
  • Script de lancement : la CLI ant réclame le travail et appelle votre script, qui lance une sandbox sur n’importe quelle plateforme.
  • Poller du SDK : votre propre code réclame le travail et lance la sandbox.

Les sections qui suivent Exécuter des sandboxes sur Kubernetes s’appliquent au script de lancement et au poller du SDK.

Exécuter des sandboxes sur Kubernetes

Anthropic publie un chart Helm, cma-sandboxes, ainsi que ses images. Le chart exécute une sandbox par session sur votre propre cluster Kubernetes. Son dispatcher interroge la file de travail de l’environnement et attribue à chaque session son propre pod :

  • Isolation : chaque pod s’exécute sous gVisor derrière les politiques réseau du chart. Il dispose de son propre système de fichiers et de ses propres limites de ressources. Seul le dispatcher détient la clé d’environnement.
  • Affinité de session : chaque message d’une session est envoyé à la sandbox de cette session. Lorsque la session est inactive depuis 30 minutes (la valeur par défaut du paramètre sandbox.idleTimeout du chart), son pod s’arrête. Son volume /workspace est conservé jusqu’à la fin de la session. Le message suivant démarre un pod sur le même volume.
  • Pool préchauffé : sauf sur Google Kubernetes Engine (GKE), le chart maintient deux pods prêts pour les nouvelles sessions (la valeur par défaut du paramètre sandbox.warmPoolSize du chart).

Les pods de sandbox exécutent le worker de la CLI ant. Ils prennent en charge les magasins de mémoire avec les paramètres de synchronisation par défaut, et ne prennent pas en charge les outils personnalisés.

Installer le chart

Le chart fonctionne sur GKE, Amazon EKS et d’autres clusters. Mettez en place les éléments suivants avant de l’installer :

  • Dans le cluster : le contrôleur Agent Sandbox (sur GKE, le module complémentaire Agent Sandbox), des nœuds qui exécutent gVisor et un plugin réseau qui applique les NetworkPolicy.
  • Dans votre propre namespace : les labels du Pod Security Standard Restricted, un Secret contenant l’ID d’environnement et la clé d’environnement, ainsi que le certificat TLS du dispatcher.

Le guide d’installation sur GitHub contient les étapes de configuration pour chaque type de cluster. Il couvre également les mises à niveau et la rotation des clés.

Enregistrez vos paramètres dans cma-values.yaml. L’installation échoue sans les trois paramètres de ce fichier :

cma-values.yaml
platform: gke             # or eks, or generic for any other cluster
egress:
  # The chart already blocks the private ranges. List your other addresses
  # that sandboxes must not reach.
  clusterCIDRs:
    - 203.0.113.10/32     # your cluster's Kubernetes API endpoint
  cmaServer:
    public: true          # the Claude API has a public address

Le guide d’installation répertorie les paramètres qui dépendent de votre cluster, comme gke.dns sur GKE Autopilot. Il indique également quand egress.clusterIsPrivate: true remplace egress.clusterCIDRs.

Ensuite, installez le chart :

helm install cma \
  oci://us-docker.pkg.dev/anthropic-public-registry/sandboxes/charts/cma-sandboxes \
  --version 0.1.0 \
  --namespace cma \
  -f cma-values.yaml \
  --wait

Après l’installation, exécutez la vérification préalable décrite dans le guide d’installation.

Ajouter des outils à l’image de sandbox

L’image de sandbox publiée est une Alpine Linux avec bash, curl, jq et la CLI ant. Le chart l’exécute avec un système de fichiers racine en lecture seule et en tant qu’utilisateur non root, de sorte qu’un agent ne peut pas installer de paquets pendant une session.

Pour donner davantage d’outils à vos agents, comme Python ou Git, construisez les deux images à partir du dépôt au tag de la version. La section Install du guide d’installation contient les commandes. Poussez les images vers votre registre sous les noms cma-dispatcher et cma-sandbox, avec la version du chart comme tag. Ensuite, définissez image.registry sur ce registre. Si vous épinglez des digests d’images, utilisez les digests de vos propres images.

Restreindre le trafic réseau sortant

Par défaut, les politiques réseau du chart permettent à une sandbox d’atteindre l’internet IPv4 public. Elles bloquent les plages d’adresses privées, le serveur de métadonnées du cloud et les adresses de egress.clusterCIDRs. Un agent victime d’une « prompt injection » (injection de prompt) peut envoyer ce qu’il lit à n’importe quelle adresse que sa sandbox peut atteindre. La section Network egress du guide d’installation fournit les détails.

  • GKE avec Dataplane V2 : définissez egress.mode: fqdnGke pour limiter les connexions au port 443 des hôtes de egress.fqdnGke.hosts. Conservez api.anthropic.com dans cette liste et ajoutez chaque hôte dont les commandes de vos agents ont besoin. Contrairement au mode par défaut, ce mode n’a pas de liste de plages bloquées. Il autorise toute adresse vers laquelle le nom d’un hôte listé est résolu, donc ne listez que des hôtes dont vous jugez le DNS fiable. Une sandbox peut toujours exfiltrer des données dans des requêtes DNS.
  • Autres clusters et GKE sans Dataplane V2 : le mode par défaut est le seul mode.
  • Tous les clusters : les politiques réseau ne couvrent pas les ports sur lesquels écoutent les propres nœuds du cluster. Consultez Node isolation you own dans le guide d’installation.

Lancer des sandboxes avec un script de lancement

Un poller sur l’hôte réclame le travail et appelle votre script une fois pour chaque élément de travail. Le script lance une sandbox pour cette session unique.

  1. Construire l’image de sandbox

    Installez ant et définissez ant beta:worker run comme point d’entrée. Lorsqu’une sandbox démarre, elle lit les détails de la session à partir des variables d’environnement, traite cette session, puis se termine. L’image de base doit fournir /bin/bash ; la construction utilise curl uniquement pour télécharger ant.

    Dockerfile
    FROM your-base-image
    ARG ANT_VERSION=2.11.0
    ARG TARGETARCH
    RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \
        curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \
          | tar -xz -C /usr/local/bin ant
    WORKDIR /workspace
    VOLUME /workspace
    ENTRYPOINT ["ant", "beta:worker", "run"]
  2. Écrire le script de lancement

    Le script transmet les détails de la session à une nouvelle sandbox. Il nécessite jq sur l’hôte du poller.

    spawn.sh
    #!/bin/bash
    # spawn.sh : appelé une fois pour chaque élément de travail réclamé.
    # L'élément de travail réclamé arrive au format JSON sur stdin.
    ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
    export ANTHROPIC_WORK_SECRET
    mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
    exec docker run --rm \
      -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
      -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
      -e ANTHROPIC_WORK_SECRET \
      -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
      your-image

    Le poller définit ANTHROPIC_WORK_ID, ANTHROPIC_ENVIRONMENT_ID, ANTHROPIC_SESSION_ID et ANTHROPIC_ENVIRONMENT_KEY. ANTHROPIC_BASE_URL n’atteint le script que si vous la définissez sur l’hôte du poller. Le script lit ANTHROPIC_WORK_SECRET à partir du JSON de l’élément de travail sur l’entrée standard. Consultez Variables d’environnement.

    /host/outputs est un répertoire de l’hôte que vous choisissez. Le monter sur /workspace vous permet de récupérer les livrables de la session après la fin de la sandbox. Le montage récupère également l’arborescence skills/ téléchargée et tous les fichiers intermédiaires.

  3. Démarrer le poller

    ant beta:worker poll --on-work ./spawn.sh

Transmettre le secret de l’élément de travail

Chaque élément de travail réclamé peut porter un secret qu’Anthropic émet pour cette session. Le worker qui exécute la session en a besoin pour monter les magasins de mémoire.

Un worker qui réclame et exécute des sessions dans un même processus transmet lui-même le secret. EnvironmentWorker avec run() est l’un de ces workers, et ant beta:worker poll sans --on-work en est un autre. Lorsque votre propre code se situe entre la réclamation et le worker, c’est vous qui transmettez le secret :

Vous réclamez le travail avecLe secret arrive sous la formeTransmettez-le au worker sous la forme
ant beta:worker poll --on-workLe champ secret du JSON de l’élément de travail sur l’entrée standard de votre scriptANTHROPIC_WORK_SECRET dans l’environnement de la sandbox
work.poller() du SDK Python, TypeScript ou GoLe champ secret de chaque élément de travail réclaméANTHROPIC_WORK_SECRET dans l’environnement de la sandbox ou l’argument work_secret de handle_item()

Transmettez le secret uniquement à la sandbox qui sert cette session, et ne le journalisez jamais. Consultez Modèle de sécurité pour savoir comment il se rapporte à la clé d’environnement.

Lancer des sandboxes depuis le poller du SDK

Pour réclamer le travail depuis votre propre code plutôt qu’avec ant beta:worker poll --on-work, utilisez le poller du SDK Python, TypeScript ou Go : work.poller(). Il interroge la file et vous remet chaque session réclamée, et c’est vous qui lancez la sandbox :

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork

SANDBOX_ENV = (
    "ANTHROPIC_ENVIRONMENT_ID",
    "ANTHROPIC_ENVIRONMENT_KEY",
    "ANTHROPIC_WORK_ID",
    "ANTHROPIC_SESSION_ID",
    "ANTHROPIC_WORK_SECRET",
    "ANTHROPIC_BASE_URL",  # forwarded only when set on this host
)


async def launch_container(work: BetaSelfHostedWork) -> None:
    print(f"claimed session {work.data.id}")
    # Remplacez `docker run` par votre propre lanceur de sandbox. Transmettez la clé d'environnement
    # (jamais votre clé API) et le secret par session de l'élément de travail : le worker
    # à l'intérieur a besoin du secret pour monter les magasins de mémoire de la session.
    env = os.environ | {
        "ANTHROPIC_WORK_ID": work.id,
        "ANTHROPIC_SESSION_ID": work.data.id,
        "ANTHROPIC_WORK_SECRET": work.secret or "",
    }
    forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
    launcher = await asyncio.create_subprocess_exec(
        "docker", "run", "--rm", "--detach", *forward, "your-image", env=env
    )
    await launcher.wait()


async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key) as client:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

Exécuter le worker du SDK dans la sandbox

Remplacez le point d’entrée ant beta:worker run par un point d’entrée du SDK lorsque la sandbox doit servir des outils personnalisés ou utiliser des paramètres de synchronisation de la mémoire autres que ceux par défaut. Le point d’entrée construit EnvironmentWorker et appelle handle_item(), qui lit les mêmes variables ANTHROPIC_* que celles transmises par le script de lancement.

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker


async def main() -> None:
    async with AsyncAnthropic(
        auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    ) as client:
        worker = EnvironmentWorker(client, workdir="/workspace")
        # Sans arguments, handle_item() lit les variables ANTHROPIC_* que le script de lancement
        # a transmises, y compris ANTHROPIC_WORK_SECRET.
        task = asyncio.create_task(worker.handle_item())
        # Annuler la tâche à l'arrêt du conteneur permet au worker de téléverser
        # les fichiers de mémoire modifiés et de supprimer les répertoires du magasin avant de quitter.
        loop = asyncio.get_running_loop()
        for signum in (signal.SIGINT, signal.SIGTERM):
            loop.add_signal_handler(signum, task.cancel)
        with contextlib.suppress(asyncio.CancelledError):
            await task


asyncio.run(main())

Préparer des fichiers pour une session

Anthropic ne monte pas de fichiers ni de dépôts GitHub dans les sandboxes auto-hébergées. Pour rendre disponibles des fichiers propres à une session :

  1. Transmettez des références de fichiers, comme un chemin S3 ou un SHA de commit, dans le champ metadata de la session.
  2. Dans votre script de lancement ou votre gestionnaire --on-work, récupérez la session (GET /v1/sessions/{session_id}) et lisez metadata. L’élément de travail réclamé porte l’ID de session, mais pas les métadonnées.
  3. Préparez les fichiers dans le répertoire de travail avant l’exécution de tout outil.

L’exemple cURL lit un « access token » (jeton d’accès) depuis ANTHROPIC_AUTH_TOKEN. Pour en obtenir un, configurez Workload Identity Federation avec la portée par défaut workspace:developer, comme décrit dans Configurer la fédération. Ensuite, échangez le jeton d’identité de votre charge de travail contre un jeton d’accès, comme illustré dans S’authentifier depuis votre charge de travail. Définissez ANTHROPIC_AUTH_TOKEN uniquement dans le shell où vous exécutez l’exemple cURL, car il a priorité sur vos paramètres de fédération. Authentification répertorie les autres identifiants acceptés par l’API, comme la clé API du démarrage rapide.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

Étapes suivantes

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

Cette page vous a-t-elle été utile ?