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
antré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.idleTimeoutdu chart), son pod s’arrête. Son volume/workspaceest 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.warmPoolSizedu 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 :
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 addressLe 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 \
--waitAprè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: fqdnGkepour limiter les connexions au port 443 des hôtes deegress.fqdnGke.hosts. Conservezapi.anthropic.comdans 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.
Construire l’image de sandbox
Installez
antet définissezant beta:worker runcomme 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 utilisecurluniquement pour téléchargerant.DockerfileFROM 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"]Écrire le script de lancement
Le script transmet les détails de la session à une nouvelle sandbox. Il nécessite
jqsur 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-imageLe poller définit
ANTHROPIC_WORK_ID,ANTHROPIC_ENVIRONMENT_ID,ANTHROPIC_SESSION_IDetANTHROPIC_ENVIRONMENT_KEY.ANTHROPIC_BASE_URLn’atteint le script que si vous la définissez sur l’hôte du poller. Le script litANTHROPIC_WORK_SECRETà partir du JSON de l’élément de travail sur l’entrée standard. Consultez Variables d’environnement./host/outputsest un répertoire de l’hôte que vous choisissez. Le monter sur/workspacevous permet de récupérer les livrables de la session après la fin de la sandbox. Le montage récupère également l’arborescenceskills/téléchargée et tous les fichiers intermédiaires.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 avec | Le secret arrive sous la forme | Transmettez-le au worker sous la forme |
|---|---|---|
ant beta:worker poll --on-work | Le champ secret du JSON de l’élément de travail sur l’entrée standard de votre script | ANTHROPIC_WORK_SECRET dans l’environnement de la sandbox |
work.poller() du SDK Python, TypeScript ou Go | Le 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 :
- Transmettez des références de fichiers, comme un chemin S3 ou un SHA de commit, dans le champ
metadatade la session. - Dans votre script de lancement ou votre gestionnaire
--on-work, récupérez la session (GET /v1/sessions/{session_id}) et lisezmetadata. L’élément de travail réclamé porte l’ID de session, mais pas les métadonnées. - 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 ?