SandboxesInicio rápido

Inicio rápido

Instalar y autenticar

Instala Lizard SDK y crea una clave API en Settings → API keys. Guárdala en LIZARD_API_KEY. Cada sandbox necesita un proyecto: pasa projectId (Python: project_id) o resuelve su ID, slug o nombre con project.

npm install @lizard-build/sdk
pip install lizard-sdk
export LIZARD_API_KEY="<your-api-key>"

Ejecutar un comando

import { Sandbox } from '@lizard-build/sdk';
 
const sandbox = await Sandbox.create('interpreter', {
  projectId: 'proj_123', timeoutMs: 300_000,
});
try {
  const result = await sandbox.process.exec("python -c 'print(2 ** 10)'");
  console.log(result.stdout, result.stderr, result.exitCode);
} finally {
  await sandbox.kill();
}
from lizard import Sandbox
 
sandbox = Sandbox.create("interpreter", project_id="proj_123", timeout_ms=300_000)
try:
    result = sandbox.process.exec_("python -c 'print(2 ** 10)'")
    print(result.stdout, result.stderr, result.exit_code)
finally:
    sandbox.kill()

Archivos

fs.write escribe texto o bytes UTF-8 válidos; fs.read lee texto. El endpoint de escritura actual no admite subidas binarias. Para descargar un archivo binario usa fs.readBytes (Python: read_bytes).

Los archivos y procesos siguen disponibles mientras el sandbox está en ejecución. Tras detenerlo, otro sandbox solo puede recuperar los archivos escritos en un Persistent Volume adjunto en /workspace. Sin volumen, /workspace es temporal. Cada volumen se adjunta a un solo sandbox y usa almacenamiento local de un nodo; exporta los archivos que deban sobrevivir a la pérdida del nodo.

await sandbox.fs.write("/tmp/task.py", "print(42)\n");
const result = await sandbox.process.exec("python /tmp/task.py");
console.log(result.stdout);

Puertos públicos

Inicia un servidor que escuche en 0.0.0.0 y llama a getHost(port) para registrar su nombre HTTPS público. El puerto es público; añade autenticación si hace falta. El sandbox deja de atender el puerto cuando se detiene.

await sandbox.process.exec(
  "nohup python -m http.server 3000 --bind 0.0.0.0 --directory /tmp >/tmp/http.log 2>&1 </dev/null &",
);
const host = await sandbox.getHost(3000);
console.log(`https://${host}`);

Conectar a un sandbox en ejecución

Crea un sandbox, ejecuta comandos y llama a kill. connect se conecta a un sandbox existente sin cambiar su estado, así que no reanuda uno pausado ni uno detenido. Pausar, reanudar, snapshot y restore están disponibles; consulta Pausa, reanudación y snapshots. Fork y la vigilancia de archivos devuelven HTTP 501. lizard sandbox ssh abre una shell interactiva con tus credenciales de la CLI. No hay acceso por el protocolo SSH, así que los clientes SSH, scp y el reenvío de puertos no funcionan.

const connected = await Sandbox.connect(sandbox.sandboxId);
console.log(await connected.getInfo());

Pausa, reanudación y snapshots

pause() guarda la memoria y los procesos en ejecución del sandbox, mantiene /workspace en su nodo y detiene la facturación. resume() restaura el sandbox con el mismo ID. Ambas llamadas ponen el trabajo en cola y responden al instante; espera al nuevo estado.

await sandbox.pause();
await sandbox.waitForStatus('paused');
await sandbox.resume();
await sandbox.waitForStatus('running');
  • La pausa cierra las conexiones de red abiertas. Los programas del sandbox deben reconectarse tras reanudar.
  • Si no se pueden guardar los procesos, el sandbox sigue en marcha y waitForStatus lanza un error con el motivo. Si falla la reanudación, el sandbox sigue pausado con su checkpoint; vuelve a llamar a resume().
  • El plazo de vida se detiene mientras el sandbox está pausado y continúa al reanudar. Un sandbox pausado no cuenta para el límite de sandboxes en marcha.
  • Un sandbox pausado se reanuda en el mismo nodo. Si ese nodo falla, se pierde el estado pausado; exporta los archivos que necesites.

Un snapshot guarda la memoria y los archivos de /workspace de un sandbox en marcha como plantilla privada del proyecto. Cada restore inicia un sandbox nuevo en la región del snapshot. Antes de capturar, cierra clientes y terminales y deja de escribir en /workspace. Los Persistent Volumes conectados no se capturan.

const saved = await sandbox.snapshot('my-app', { poolSize: 5 });
await Sandbox.waitForSnapshot(saved.id);
const copy = await Sandbox.restore(saved.id);

Lizard mantiene cinco copias listas por defecto (de una a diez), así que un restore arranca desde una copia lista. Si no hay ninguna, restore puede devolver HTTP 503 hasta que el pool se rellene. Un sandbox restaurado se factura por consumo medido; size no se aplica. En la CLI, usa lizard sandbox pause <id>, lizard sandbox resume <id>, lizard sandbox snapshot <id> --name my-app y lizard sandbox restore <snapshot-id>.

Límites actuales del runtime

El SDK y la CLI fijan cinco minutos de duración por defecto. La API directa y el panel no fijan caducidad por defecto. Indica la duración: timeoutMs: 0 al crear desactiva la caducidad; un valor positivo fija un plazo. setTimeout acepta 1000–2147483647 ms, no cero. Los comandos no reinician el plazo. No es un temporizador de inactividad.

Los resultados incluyen stdout, stderr y el código de salida. El tiempo máximo de un comando está entre 1 y 600 segundos. El runtime actual no aplica las opciones envs, workdir ni user; fija el directorio y las variables en el comando de shell. Tampoco aplica envs ni metadata al crear.

Inicio rápido · Referencia del SDK · Ejecutar Python · Panel · Persistent Volumes

ResumenReferencia del SDK