Sandboxes autoalojados

De forma predeterminada, Managed Agents ejecuta herramientas y código dentro de sandboxes en la nube gestionados por Anthropic. Los sandboxes autoalojados mantienen la orquestación del lado de Anthropic, pero trasladan la ejecución de herramientas a infraestructura que tú controlas, de modo que el código del agente, el sistema de archivos y el tráfico de red saliente nunca salen de tu entorno.

La ejecución de herramientas permanece en tu host: el sistema de archivos que el agente lee y escribe, los procesos que genera y la red a la que puede acceder están todos bajo tu control. Las entradas y salidas de las herramientas siguen fluyendo hacia el plano de control de Anthropic (donde se ejecuta Claude) para que el modelo pueda ver los resultados y determinar qué hacer a continuación. Consulta el modelo de seguridad para conocer el límite completo del flujo de datos.

En qué se diferencia de los entornos en la nube

El autoalojamiento es una buena opción cuando el agente necesita operar sobre datos que no pueden salir del perímetro de tu red, acceder a servicios internos que no son enrutables públicamente, o ejecutarse bajo los controles de cumplimiento y auditoría propios de tu organización.

Para la elegibilidad de Zero Data Retention y HIPAA BAA, consulta API y retención de datos.

Cuándo combinar con túneles MCP

El autoalojamiento controla dónde se ejecuta el código del agente. Los túneles MCP controlan cómo Anthropic accede a los servidores MCP en tu red. Son independientes: una sesión que se ejecuta en los sandboxes en la nube de Anthropic puede seguir accediendo a servidores MCP privados a través de un túnel, y una sesión autoalojada puede usar servidores MCP tunelizados o públicos. Usa ambos cuando quieras que tanto la ejecución como el acceso a herramientas permanezcan dentro de tu perímetro.

Worker de entorno

Un "environment worker" (worker de entorno) es un proceso que ejecutas en tu propia infraestructura. Recibe solicitudes de ejecución de herramientas de Anthropic y las ejecuta localmente. El entorno self_hosted actúa como una cola de trabajo: cuando se le asigna una sesión, Anthropic encola la sesión como un elemento de trabajo. Tu worker reclama elementos de trabajo de esa cola, genera un contexto de ejecución para cada uno, descarga las skills del agente (recursos reutilizables basados en el sistema de archivos que proporcionan al agente experiencia específica de dominio), ejecuta las llamadas a herramientas y publica los resultados de vuelta.

Los elementos de trabajo se reclaman sondeando la cola del entorno: ya sea mediante un worker siempre activo que sondea continuamente, o un handler activado por webhook que se despierta con session.status_run_started y comienza a sondear.

Tanto la CLI como el SDK incluyen workers preconstruidos. La CLI ant solo admite el patrón siempre activo; el SDK admite tanto el siempre activo como el activado por webhook. Ambos son configurables: consulta Worker autoalojado en la referencia para los flags de la CLI, y Helpers del SDK en esta página para las opciones del SDK. Para mayor control, llama directamente a los endpoints de Environments Work e implementa tu propio worker. En Claude Platform on AWS, el endpoint de listado GET /v1/environments/{id}/work y su equivalente en el SDK no están disponibles actualmente; los demás endpoints de trabajo (poll, ack, heartbeat, stop, post results, get por elemento y stats) funcionan normalmente.

Sistema de archivos del sandbox

• /workspace: el directorio de trabajo predeterminado del sistema para la ejecución de herramientas y la descarga de skills. El flag --workdir de la CLI usa por defecto el directorio actual; pasa --workdir /workspace para coincidir con el valor predeterminado del sistema. Las skills se descargan en <workdir>/skills/<name>/. Si usas un directorio de trabajo diferente, actualiza la indicación del sistema de tu agente para que Claude pueda localizar los archivos de skills.
• /mnt/session/outputs: el harness del worker indica a Claude que escriba los entregables finales aquí. En modo sandbox, monta un directorio del host en esta ruta para recuperar las salidas después de que finalice la sesión. En modo in-process, las herramientas de archivos del worker escriben bajo el directorio de trabajo, por lo que esta ruta no aplica.

Antes de comenzar

Necesitas:

• Un agente existente. Si no tienes uno, completa primero el Quickstart y anota su ID de agente.
• Un host Linux con /bin/bash en esa ruta exacta. El SDK de TypeScript requiere adicionalmente unzip, tar y Node.js 22 o posterior; el SDK de Python usa la biblioteca estándar para la extracción de archivos y no tiene requisitos binarios adicionales. Estas dependencias se resuelven en rutas fijas y no respetan las modificaciones de PATH.
• La CLI ant o un SDK de Anthropic (Python, TypeScript o Go) en el host del worker.
• Dos credenciales: una clave de entorno (generada en los pasos siguientes) autentica al worker ante su cola; tu clave de API de Claude crea sesiones y lee estadísticas de la cola desde fuera del host del worker.

Ejecutar un worker

Elige siempre activo para la configuración más simple: un proceso de larga duración sondea la cola continuamente y solo necesita HTTPS saliente. Elige activado por webhook para evitar ejecutar un poller inactivo; requiere un endpoint de webhook al que Anthropic pueda acceder (consulta Webhooks para la configuración del endpoint y la verificación de firmas).

Helpers del SDK

El SDK proporciona tres helpers con diferentes niveles de control. EnvironmentWorker cubre la mayoría de los casos de uso; recurre a los helpers de nivel inferior cuando necesites lanzar tu propio proceso por sesión o ejecutar herramientas contra una sesión ya reclamada.

• EnvironmentWorker: el worker listo para usar. Gestiona el sondeo, la configuración y la ejecución de principio a fin.
  • .run(): se ejecuta indefinidamente, recogiendo sesiones a medida que llegan. Finaliza limpiamente con SIGTERM.
  • .handle_item(): recoge una sesión pendiente, la gestiona y finaliza.
• work.poller(): sondea la cola de trabajo por ti y te entrega cada sesión reclamada. Úsalo cuando quieras decidir qué sucede con cada sesión, por ejemplo, lanzar un sandbox en lugar de ejecutar herramientas in-process.
  • drain: si se debe dejar de sondear una vez que la cola esté vacía en lugar de esperar nuevo trabajo.
  • block_ms: cuánto tiempo esperar a que llegue trabajo antes de retornar, en milisegundos. Debe estar entre 1 y 999 (espera por sondeo; el helper vuelve a sondear automáticamente). Pasa null (None en Python, param.Null[int64]() en Go) para una comprobación no bloqueante; omitir el parámetro usa el long-poll predeterminado de 999 ms.
  • reclaim_older_than_ms: volver a reclamar elementos de trabajo asignados a un worker que ha dejado de responder.
  • auto_stop: si se debe publicar una señal de parada en el elemento de trabajo después de que el iterador finalice. El poller de Go no tiene opción de desactivación y siempre publica la señal de parada, así que bloquea en el cuerpo del bucle hasta que la sesión se complete en lugar de desacoplarte.
• client.beta.sessions.events.tool_runner(): ejecuta llamadas a herramientas para una sola sesión, dado el ID de sesión y una lista de herramientas. Úsalo cuando ya hayas reclamado el trabajo y solo necesites la capa de ejecución.

Usa el poller de trabajo directamente cuando quieras lanzar tu propio proceso por sesión, por ejemplo, iniciando un sandbox para cada sesión reclamada:

import asyncio
import os

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


async def launch_container(work: BetaSelfHostedWork) -> None:
    # Reemplaza esto con tu propio lanzador de sandbox por sesión. Pasa
    # ANTHROPIC_ENVIRONMENT_KEY al sandbox lanzado, nunca
    # tu clave de API.
    print(f"claimed session {work.data.id}")


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())

AgentToolContext es el contexto de ejecución para las llamadas a herramientas. Define el directorio de trabajo y la política de rutas, y opcionalmente descarga las skills de la sesión cuando se usa como context manager. beta_agent_toolset_20260401(env) toma un AgentToolContext y devuelve las implementaciones de herramientas estándar (bash, read, write, edit, glob, grep).

Con EnvironmentWorker: ambos se gestionan automáticamente. Pasa una factory tools para personalizar la lista de herramientas:

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

Con work.poller() y tool_runner(): pasa una lista de herramientas como tools a client.beta.sessions.events.tool_runner(). Para construir esa lista, configura AgentToolContext tú mismo y llama a beta_agent_toolset_20260401(env):

from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # skills downloaded to /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

Verifica que el worker esté conectado

Desde un shell separado, usando tu clave de API de Claude (no la clave de entorno), confirma que workers_polling sea al menos 1:

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

Si workers_polling permanece en 0, el worker no está alcanzando la cola: confirma que ANTHROPIC_ENVIRONMENT_KEY y ANTHROPIC_ENVIRONMENT_ID estén configuradas en el host del worker. Consulta Leer la profundidad de la cola para la respuesta completa de estadísticas y ejemplos en otros lenguajes.

Iniciar una sesión

Una vez que tu worker esté en ejecución, crea una sesión que apunte al entorno. La sesión entra en la cola de trabajo del entorno y espera allí hasta que un worker la reclame; si no hay ningún worker conectado, la sesión permanece en cola en lugar de fallar.

Anthropic no monta archivos ni repositorios de GitHub en sandboxes autoalojados. Para hacer disponibles archivos específicos de la sesión, pasa referencias de archivos (como una ruta de S3 o un SHA de commit) en el campo metadata de la sesión. Tu script de spawn o handler --on-work lee esos metadatos del elemento de trabajo reclamado (a través de los endpoints de Environments Work) y prepara los archivos en el directorio de trabajo antes de que comience la ejecución de herramientas.

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

Consulta Worker autoalojado en la referencia para la lista completa de flags de la CLI, y Helpers del SDK para las opciones de los helpers del SDK.

Monitoreo y operaciones

Estas llamadas se ejecutan desde tus herramientas de monitoreo u operaciones, autenticadas con tu clave de API de Claude, para observar y gestionar la flota de workers. El bucle de reclamación y keep-alive se gestiona dentro de los helpers del worker, por lo que no llamas a esos endpoints directamente.

Leer la profundidad de la cola

work.stats devuelve el estado de la cola para un entorno:

• depth es el número de elementos esperando ser reclamados. Escala tu flota de workers o genera alertas de acumulación según este valor.
• pending es el número de elementos que un worker ha reclamado y está procesando actualmente.
• oldest_queued_at es la marca de tiempo del elemento más antiguo en la cola, o null si la cola está vacía.
• workers_polling es el número de workers que han sondeado en los últimos 30 segundos. Úsalo para alertas de disponibilidad.

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

Detener una sesión de forma ordenada

Usa work.stop para pedirle al worker que gestiona una sesión específica que la cierre limpiamente. El worker finaliza cualquier llamada a herramienta en curso, publica un estado final y libera la sesión. Pasa force: true en el cuerpo de la solicitud para interrumpir inmediatamente en lugar de esperar a que se complete la llamada a herramienta actual.

Dado que estas llamadas se ejecutan desde tus herramientas de operaciones en lugar del host del worker, ANTHROPIC_WORK_ID no se configura automáticamente. Configúrala con el ID del elemento de trabajo objetivo antes de ejecutar los siguientes ejemplos.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)

Próximos pasos