Sandbox de Claude Agent SDK: ejecuta cada tarea en su propio espacio de trabajo

Un sandbox de Claude Agent SDK es el entorno donde se ejecutan el proceso del agente del SDK y sus herramientas, y donde residen sus archivos de trabajo. El SDK inicia un subproceso de Claude CLI. Darle a ese proceso una máquina virtual o un contenedor separado te permite definir a qué archivos y credenciales puede acceder y qué ocurre cuando termina la tarea. Establecer un directorio de trabajo por sí solo no crea ese límite. Guía de alojamiento de Anthropic

Usa un espacio de trabajo por tarea para trabajos independientes. Para una sesión que abarque varias solicitudes, conserva el espacio de trabajo o guarda el estado necesario para reanudarla. Mantén la autenticación, la asignación de propietarios a las tareas y la programación en un coordinador fuera de la máquina del agente.

Somos los creadores de Lizard. Esta guía usa Lizard Sandboxes para un pequeño ejemplo de configuración y compara las opciones de alojamiento. Verificamos las API y los comandos el 4 de noviembre de 2026. Revisamos el nuevo ejemplo del SDK con la documentación; no lo hemos ejecutado contra Anthropic en un sandbox en la nube.

Qué debe proporcionar el host

El Agent SDK necesita un entorno de ejecución, un subproceso de CLI, un directorio de trabajo y acceso al servicio del modelo. El subproceso también puede iniciar herramientas que usen más memoria, CPU y disco que el propio SDK. Ajusta el tamaño del espacio de trabajo a la tarea: leer unos pocos archivos difiere de compilar un repositorio o controlar un navegador.

Los directorios locales separan el estado de la aplicación, pero los procesos con los mismos permisos de acceso del sistema operativo aún pueden acceder a otros directorios. Para usuarios sin relación entre sí, usa un límite acorde con ese riesgo. La guía de despliegue seguro de Anthropic trata el aislamiento y las credenciales.

Elegir dónde alojarlo

Lizard Sandboxes ofrece microVMs de Firecracker con sus propios kernels, plantillas listas para usar, ejecución de comandos y transferencia de archivos. Son adecuadas para tareas de CPU que se ajusten a los tamaños fijos de las máquinas. Lizard no ofrece instancias de sandbox con GPU ni plantillas de sandbox basadas en Dockerfiles arbitrarios. Lizard Sandboxes

E2B ofrece sandboxes de Linux, plantillas y API de ejecución de código. Daytona ofrece herramientas para espacios de trabajo y varias clases de entornos de ejecución. Modal admite recursos elásticos de CPU y flujos de trabajo con GPU, con restricciones propias de cada entorno de ejecución. Un despliegue de Docker o Kubernetes te da control sobre tu propia infraestructura, mientras tú gestionas la capacidad, el aislamiento y la limpieza. E2B, Daytona, Modal

El SDK puede ejecutarse en un host con el entorno de ejecución necesario y soporte para subprocesos; no requiere un proveedor de sandbox en particular. Comprueba las dependencias, el acceso a la red, el comportamiento al detenerse y la memoria con tu propia carga de trabajo.

Comenzar con una pequeña tarea del SDK de solo lectura

Este ejemplo lee un archivo de proyecto local y le pide a Claude un resumen. Solo pone las herramientas Read, Glob y Grep a disposición del agente. No necesita ejecución de Bash sin restricciones ni omisión de permisos.

Necesitas un proyecto de Lizard y una sesión iniciada en Lizard CLI, además de una clave API de Anthropic para las llamadas al modelo. La computación de Lizard y el uso de Anthropic se facturan por separado. Instala la CLI siguiendo las instrucciones actuales.

1. Crear un espacio de trabajo Small

Reemplaza el marcador del proyecto y luego copia el ID del sandbox devuelto en SB:

lizard sandbox create --project YOUR_PROJECT_ID \
  --template claude --size small --timeout 3600000 --json
SB=YOUR_SANDBOX_ID
lizard sandbox exec "$SB" -- mkdir -p /workspace/agent

El tiempo de vida explícito es de una hora. El valor predeterminado de la CLI es de cinco minutos, y ejecutar comandos no restablece ese plazo. Establece un plazo adecuado para el trabajo y guarda los resultados antes de que expire. CLI de sandbox

2. Guardar el script del SDK localmente

Crea summarize.mjs con este código:

import { query } from '@anthropic-ai/claude-agent-sdk';

if (!process.env.ANTHROPIC_API_KEY) {
  throw new Error('Set ANTHROPIC_API_KEY inside the task environment');
}

let completed = false;
for await (const message of query({
  prompt: 'Read README.md and summarize the project in two sentences.',
  options: {
    cwd: '/workspace/agent',
    settingSources: [],
    tools: ['Read', 'Glob', 'Grep'],
    allowedTools: ['Read', 'Glob', 'Grep'],
    permissionMode: 'dontAsk',
    maxTurns: 6,
  },
})) {
  if (message.type !== 'result') continue;
  if (message.subtype !== 'success' || message.is_error) {
    throw new Error(`Agent failed: ${message.subtype}`);
  }
  completed = true;
  console.log(message.result);
}
if (!completed) throw new Error('Agent ended without a successful result');

tools selecciona las herramientas integradas disponibles. allowedTools aprueba las llamadas de antemano; por sí solo, no constituye una lista completa de herramientas permitidas. dontAsk deniega las solicitudes que carecen de permiso. El límite bajo de turnos acota el bucle del agente de este ejemplo; no limita el gasto total en la nube. Referencia del Agent SDK

Crea un pequeño README.md junto al script y luego sube ambos archivos:

lizard sandbox files put "$SB" ./summarize.mjs /workspace/agent/summarize.mjs
lizard sandbox files put "$SB" ./README.md /workspace/agent/README.md
lizard sandbox shell "$SB"

3. Instalar y ejecutar dentro del espacio de trabajo

En el shell de Bash del sandbox:

cd /workspace/agent
npm init -y
npm install --save-exact @anthropic-ai/claude-agent-sdk
read -rsp 'Anthropic API key: ' ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY
node summarize.mjs
unset ANTHROPIC_API_KEY

El resultado esperado es un resumen breve en stdout y un código de salida de cero. Una credencial ausente, una operación denegada o un límite de turnos agotado deberían producir una ejecución fallida. Conserva el archivo de bloqueo generado y usa npm ci cuando conviertas el ejemplo en un entorno repetible.

La solicitud interactiva evita que la clave quede en el historial del shell. La clave sigue presente dentro del entorno del agente mientras se ejecuta la tarea. Para un servicio que ejecute trabajo no confiable, considera un proxy de salida que inyecte las credenciales fuera del sandbox. Autenticación y alojamiento del SDK

4. Exportar lo que necesitas y luego pausar

Sal del shell del sandbox y recupera los archivos de salida mediante lizard sandbox files get. Una vez que hayas guardado el resultado:

lizard sandbox pause "$SB"

Confirma que el estado final sea paused. Una pausa exitosa detiene los cargos de computación y conserva el estado del espacio de trabajo; el almacenamiento de Persistent Volumes se factura por separado. El disco local de este ejemplo no se convierte en almacenamiento duradero solo porque su ruta comience con /workspace. Persistencia, Persistent Volumes

Agregar funciones de producción en torno al script

Crea un registro de tarea para cada solicitud antes de iniciar un agente. Guarda el propietario, el ID del sandbox, el estado, el plazo y la ubicación de los resultados. Transmite el progreso a través del coordinador y conserva el resultado final con independencia de la conexión del cliente.

Gestiona la cancelación y la limpieza por separado. La desconexión de un cliente no tiene por qué cancelar un trabajo útil; una tarea cancelada no debería dejar una máquina ejecutándose sin que se sepa. Reintenta la limpieza tras fallos temporales y concilia los registros de tareas con los estados reales de los sandboxes.

Para las sesiones, guarda el ID de la sesión, la transcripción necesaria y el estado de los archivos. Una fila de base de datos que contenga solo el ID no puede recrear los archivos que falten en el espacio de trabajo. Anthropic documenta el almacenamiento de sesiones por separado de los archivos del directorio de trabajo. Sesiones, estado del alojamiento

Mantén el estado de las plantillas reutilizables libre de credenciales de usuario y archivos privados de las tareas. Restaura ese estado limpio para cada tarea independiente. No permitas que la máquina pausada de un usuario se convierta en el espacio de trabajo de otro sin un restablecimiento probado.

Cuánto cuesta el espacio de trabajo

Lizard Small cuesta $0.0162 por hora de ejecución. Cien horas acumuladas de ejecución consumen $1.62 de computación; una cuenta Pro nueva sigue teniendo un mínimo mensual de $19 con $19 de uso incluido. Las llamadas al modelo, Persistent Volumes y otros recursos necesitan su propio presupuesto. Precios de Lizard

Pro admite 20 sandboxes Small a la vez y 400 nuevos inicios por día, con límites de inicios por minuto y por hora también. Pro 5x cuesta $99 con $99 de uso y admite hasta 110 sandboxes Small; Pro 20x cuesta $499 con $499 de uso y admite hasta 600. Una mayor concurrencia no significa que cada tarea termine a la misma velocidad. Límites actuales

Mide el tiempo total de ejecución, incluida la instalación de paquetes, las esperas del modelo y la transferencia de resultados. Si pausas un espacio de trabajo entre solicitudes, el coordinador debe permanecer fuera de él: un proceso pausado no puede recibir la solicitud que lo reactiva.

¿Es un sandbox el directorio de trabajo de Claude Agent SDK? No. cwd elige dónde trabaja el proceso. Usa controles del sistema operativo o un contenedor o máquina virtual separados para definir el acceso más allá de ese directorio.

¿Puedo empezar con Claude Code en lugar de escribir un servicio con el SDK? Sí. Para una sola tarea de programación, la guía de sandbox de Claude Code muestra el flujo de trabajo más corto con la CLI. Usa el SDK cuando tu aplicación necesite gestionar los mensajes del agente, la política de herramientas y el comportamiento de las sesiones mediante código.