Ejecutar un sandbox por sesión
Da a cada sesión su propio sandbox autoalojado con el chart de Helm en Kubernetes, un script de lanzamiento o el sondeador del SDK.
En el patrón de un sandbox por sesión, cada sesión se ejecuta en un “sandbox” (entorno aislado) nuevo, que puede tener su propio sistema de archivos, límites de recursos y controles de red. Para compararlo con los otros patrones, consulta Elige un patrón de implementación.
Puedes configurarlo de tres maneras:
- Chart de Helm en Kubernetes: El despachador de Anthropic reclama el trabajo e inicia un pod para cada sesión en tu clúster.
- Script de lanzamiento: La CLI
antreclama el trabajo y llama a tu script, que lanza un sandbox en cualquier plataforma. - Sondeador del SDK: Tu propio código reclama el trabajo y lanza el sandbox.
Las secciones posteriores a Ejecuta sandboxes en Kubernetes se aplican al script de lanzamiento y al sondeador del SDK.
Ejecuta sandboxes en Kubernetes
Anthropic publica un chart de Helm, cma-sandboxes, y sus imágenes. El chart ejecuta un sandbox por sesión en tu propio clúster de Kubernetes. Su despachador sondea la cola de trabajo del entorno y le da a cada sesión un pod propio:
- Aislamiento: Cada pod se ejecuta bajo gVisor detrás de las políticas de red del chart. Tiene su propio sistema de archivos y límites de recursos. Solo el despachador tiene la clave del entorno.
- Afinidad de sesión: Cada mensaje de una sesión va al sandbox de esa sesión. Después de que la sesión permanece inactiva durante 30 minutos (el valor predeterminado de la configuración
sandbox.idleTimeoutdel chart), su pod se detiene. Su volumen/workspacepermanece hasta que la sesión termina. El siguiente mensaje inicia un pod sobre el mismo volumen. - “Warm pool” (grupo precalentado): Excepto en Google Kubernetes Engine (GKE), el chart mantiene dos pods listos para nuevas sesiones (el valor predeterminado de la configuración
sandbox.warmPoolSizedel chart).
Los pods de sandbox ejecutan el “worker” (proceso de trabajo) de la CLI ant. Admiten almacenes de memoria con la configuración de sincronización predeterminada, y no admiten herramientas personalizadas.
Instala el chart
El chart se ejecuta en GKE, Amazon EKS y otros clústeres. Configura lo siguiente antes de instalarlo:
- En el clúster: El controlador de Agent Sandbox (en GKE, el complemento Agent Sandbox), nodos que ejecuten gVisor y un complemento de red que aplique NetworkPolicy.
- En tu propio espacio de nombres: Etiquetas del Pod Security Standard restringido, un Secret con el ID del entorno y la clave del entorno, y el certificado TLS del despachador.
La guía de instalación en GitHub tiene los pasos de configuración para cada tipo de clúster. También cubre las actualizaciones y la rotación de claves.
Guarda tu configuración como cma-values.yaml. La instalación falla sin las tres configuraciones de este archivo:
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 addressLa guía de instalación enumera las configuraciones que dependen de tu clúster, como gke.dns en GKE Autopilot. También indica cuándo egress.clusterIsPrivate: true reemplaza a egress.clusterCIDRs.
Luego, instala el 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 \
--waitDespués de la instalación, ejecuta la comprobación previa que describe la guía de instalación.
Agrega herramientas a la imagen del sandbox
La imagen de sandbox publicada es Alpine Linux con bash, curl, jq y la CLI ant. El chart la ejecuta con un sistema de archivos raíz de solo lectura y como usuario no root, por lo que un agente no puede instalar paquetes durante una sesión.
Para darles más herramientas a tus agentes, como Python o Git, compila ambas imágenes desde el repositorio en la etiqueta de la versión. La sección Install de la guía de instalación tiene los comandos. Sube las imágenes a tu registro como cma-dispatcher y cma-sandbox, con la versión del chart como etiqueta. Luego, establece image.registry en ese registro. Si fijas digests de imagen, usa los digests de tus propias imágenes.
Restringe el tráfico de salida de red
De forma predeterminada, las políticas de red del chart permiten que un sandbox acceda a la internet IPv4 pública. Bloquean los rangos de direcciones privadas, el servidor de metadatos de la nube y las direcciones de egress.clusterCIDRs. Un agente afectado por “prompt injection” (inyección de prompts) puede enviar lo que lee a cualquier dirección a la que su sandbox pueda acceder. Network egress en la guía de instalación tiene los detalles.
- GKE con Dataplane V2: Establece
egress.mode: fqdnGkepara limitar las conexiones al puerto 443 de los hosts deegress.fqdnGke.hosts. Manténapi.anthropic.comen esa lista y agrega todos los hosts que necesiten los comandos de tus agentes. A diferencia del modo predeterminado, este modo no tiene una lista de rangos bloqueados. Permite cualquier dirección a la que resuelva el nombre de un host de la lista, así que incluye solo hosts cuyo DNS sea de tu confianza. Aun así, un sandbox puede enviar datos al exterior dentro de las consultas DNS. - Otros clústeres y GKE sin Dataplane V2: El modo predeterminado es el único modo.
- Todos los clústeres: Las políticas de red no cubren los puertos en los que escuchan los propios nodos del clúster. Consulta Node isolation you own en la guía de instalación.
Lanza sandboxes con un script de lanzamiento
Un sondeador en el host reclama el trabajo y llama a tu script una vez por cada elemento de trabajo. El script lanza un sandbox para esa única sesión.
Compila la imagen del sandbox
Instala
anty estableceant beta:worker runcomo punto de entrada. Cuando un sandbox se inicia, lee los detalles de la sesión desde variables de entorno, gestiona esa sesión y termina. La imagen base debe proporcionar/bin/bash; la compilación usacurlsolo para descargarant.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"]Escribe el script de lanzamiento
El script reenvía los detalles de la sesión a un sandbox nuevo. Requiere
jqen el host del sondeador.spawn.sh#!/bin/bash # spawn.sh: se invoca una vez por cada elemento de trabajo reclamado # El elemento de trabajo reclamado llega como JSON por 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-imageEl sondeador establece
ANTHROPIC_WORK_ID,ANTHROPIC_ENVIRONMENT_ID,ANTHROPIC_SESSION_IDyANTHROPIC_ENVIRONMENT_KEY.ANTHROPIC_BASE_URLllega al script solo si la estableces en el host del sondeador. El script leeANTHROPIC_WORK_SECRETdel JSON del elemento de trabajo en la entrada estándar. Consulta Variables de entorno./host/outputses un directorio del host que tú eliges. Montarlo en/workspacete permite recuperar los entregables de la sesión después de que el sandbox termine. El montaje también recoge el árbolskills/descargado y cualquier archivo intermedio.Inicia el sondeador
ant beta:worker poll --on-work ./spawn.sh
Reenvía el secreto del elemento de trabajo
Cada elemento de trabajo reclamado puede llevar un secret que Anthropic emite para esa sesión. El worker que ejecuta la sesión lo necesita para montar almacenes de memoria.
Un worker que reclama y ejecuta sesiones en un mismo proceso transmite el secreto por sí mismo. EnvironmentWorker con run() es uno de esos workers, y ant beta:worker poll sin --on-work es otro. Cuando tu propio código se sitúa entre la reclamación y el worker, tú reenvías el secreto:
| Reclamas trabajo con | El secreto llega como | Pásalo al worker como |
|---|---|---|
ant beta:worker poll --on-work | El campo secret del JSON del elemento de trabajo en la entrada estándar de tu script | ANTHROPIC_WORK_SECRET en el entorno del sandbox |
work.poller() del SDK de Python, TypeScript o Go | El campo secret de cada elemento de trabajo reclamado | ANTHROPIC_WORK_SECRET en el entorno del sandbox o el argumento work_secret de handle_item() |
Pasa el secreto solo al sandbox que atiende esa sesión y nunca lo registres en los logs. Consulta Modelo de seguridad para ver cómo se relaciona con la clave del entorno.
Lanza sandboxes desde el sondeador del SDK
Para reclamar trabajo desde tu propio código en lugar de ant beta:worker poll --on-work, usa el sondeador del SDK de Python, TypeScript o Go: work.poller(). Sondea la cola y te entrega cada sesión reclamada, y tú lanzas el 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}")
# Reemplaza `docker run` con tu propio lanzador de sandboxes. Reenvía la clave del
# entorno (nunca tu clave de API) y el secreto por sesión del elemento de trabajo: el worker
# interno necesita el secreto para montar los almacenes de memoria de la sesión.
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())Ejecuta el worker del SDK dentro del sandbox
Reemplaza el punto de entrada ant beta:worker run por un punto de entrada del SDK cuando el sandbox deba atender herramientas personalizadas o usar una configuración de sincronización de memoria no predeterminada. El punto de entrada construye EnvironmentWorker y llama a handle_item(), que lee las mismas variables ANTHROPIC_* que reenvía el script de lanzamiento.
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")
# Sin argumentos, handle_item() lee las variables ANTHROPIC_* que el script de lanzamiento
# reenvió, incluida ANTHROPIC_WORK_SECRET.
task = asyncio.create_task(worker.handle_item())
# Cancelar la tarea cuando se detiene el contenedor permite que el worker suba
# los archivos de memoria modificados y elimine los directorios del almacén antes de salir.
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())Prepara archivos para una sesión
Anthropic no monta archivos ni repositorios de GitHub en los sandboxes autoalojados. Para que los archivos específicos de una sesión estén disponibles:
- Pasa referencias a archivos, como una ruta de S3 o un SHA de commit, en el campo
metadatade la sesión. - En tu script de lanzamiento o en tu controlador de
--on-work, recupera la sesión (GET /v1/sessions/{session_id}) y leemetadata. El elemento de trabajo reclamado lleva el ID de la sesión, pero no los metadatos. - Prepara los archivos en el directorio de trabajo antes de que se ejecute cualquier herramienta.
El ejemplo de cURL lee un token de acceso de ANTHROPIC_AUTH_TOKEN. Para obtener uno, configura Workload Identity Federation con el alcance predeterminado workspace:developer, como se describe en Configurar la federación. Luego, intercambia el token de identidad de tu carga de trabajo por un token de acceso, como se muestra en Autentícate desde tu carga de trabajo. Establece ANTHROPIC_AUTH_TOKEN solo en la shell donde ejecutes el ejemplo de cURL, porque tiene prioridad sobre tu configuración de federación. Autenticación enumera las demás credenciales que acepta la API, como la clave de API de la guía de inicio rápido.
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
metadata={"input_file": "s3://my-bucket/data.csv"},
)Próximos pasos
Consulta la profundidad de la cola, detén sesiones y workers de forma limpia y corrige fallos comunes.
¿Te resultó útil esta página?