Sandboxes

Un sandbox es una micro-VM aislada de Firecracker que levantas bajo demanda, ejecutas código dentro y desmontas cuando terminas. Cada uno es un entorno Linux completo con su propio sistema de archivos, red y espacio de nombres de procesos — iniciado en milisegundos, no en minutos.

Sandboxes son la primitiva de cómputo detrás de los agentes de IA, intérpretes de código, evals y trabajos de estilo CI en Lizard. Mientras que un service es un despliegue de larga duración vinculado a un repo, un sandbox es efímero, programable y desechable — crea un sandbox para cada tarea dentro de la capacidad disponible para tu cuenta.

import { Sandbox } from '@lizard-build/sdk';
 
const sandbox = await Sandbox.create('base', { project: 'my-project' });
const { stdout } = await sandbox.process.exec('echo "hello from Lizard"');
console.log(stdout);            // hello from Lizard
await sandbox.kill();

Cuándo usar un sandbox

Una vez que un agente ha producido una app funcional dentro de un sandbox, puedes promoverla a un service persistente con lizard up — sin necesidad de Dockerfile.

Qué los hace rápidos

• Micro-VMs de Firecracker — un invitado Linux independiente para cada sandbox. Los runtimes de aplicaciones tienen distintas reglas de aislamiento. La virtualización por hardware separa el invitado del host. Controla las credenciales y el acceso de red del código en el que no confías.
• Pausar y reanudar — al pausar se congelan las vCPU de la micro-VM. La memoria, el sistema de archivos y los procesos en ejecución se mantienen tal como están, así que al reanudar se retoma exactamente donde se quedó — sin reinstalar paquetes ni recalentar cachés. Esto es lo que permite que las sesiones de agentes de larga duración sobrevivan entre invocaciones separadas. El estado se mantiene en la memoria del host en lugar de escribirse en disco, por lo que no sobrevive a un fallo del host. Consulta pause & resume.
• Arranque desde una plantilla — cada nodo preconstruye una instantánea dorada por plantilla, así que create es una restauración, no un arranque en frío.

Plantillas

Un sandbox arranca desde una template (también llamada snapshot en el dashboard). Hay dos integradas:

base es la opción predeterminada. La API pública de creación acepta estos dos nombres de plantilla. No expone un flujo de carga de plantillas personalizadas.

Ciclo de vida

Un sandbox pasa por tres estados:

create ──▶ running ⇄ paused ──▶ stopped
                              (killed or expired)

• running — el invitado puede ejecutar comandos, trabajar con archivos y servir puertos expuestos.
• paused — las vCPU se detienen. La memoria del invitado y el estado de los procesos permanecen en el host; esto no es una instantánea duradera ni una copia de seguridad.
• stopped — el sandbox terminó por eliminación o expiración. Su sistema de archivos local ya no está disponible.

El SDK envía por defecto una duración de cinco minutos. La API de creación sin procesar acepta timeoutMs: 0 para no tener expiración. Pasa un tiempo de espera explícito cuando un script deba comportarse igual en todos los clientes, y libera el sandbox cuando termine la tarea. Los comandos no reinician la duración.

La pausa está pensada para preservar el tiempo de ejecución restante. Revisa el problema actual del ciclo de vida antes de depender de una pausa más larga que la fecha límite original. Los archivos persistentes deben ir en un volume; un invitado en pausa no sobrevive a un fallo del host.

Recursos y límites

Cada sandbox se ejecuta con 4 vCPU / 4096 MiB RAM fijos. La API pública de creación no tiene una configuración de tamaño por sandbox. Cada sandbox hereda los recursos de su plantilla.

La región se elige automáticamente según la capacidad disponible; en el dashboard puedes fijar una. No asumas que las cuotas de app y la capacidad de sandbox usan las mismas reglas de aplicación. Consulta limits.

Formas de usar Sandboxes