SandboxesPersistent Volumes

Persistent Volumes

Un volumen en Lizard (lizard.build) conserva los datos cuando un sandbox se detiene. Se monta en /workspace y se conecta a una soel sandbox a la vez. La Sandbox se ejecuta en el mismo nodo que su volumen.

Crear y conectar por nombre

Los nombres son únicos dentro de cada proyecto. Usa letras minúsculas, números y guiones, hasta 64 caracteres. El nombre debe empezar y terminar con una letra o un número.

Usa getOrCreate para reutilizar un volumen con nombre. El tamaño solo se aplica al crear un volumen nuevo; nunca cambia el tamaño de uno existente. Volume.create devuelve un conflicto si el nombre ya existe.

import { Sandbox, Volume } from '@lizard-build/sdk';
 
await Volume.getOrCreate('proj_123', 'agent-workdir', { sizeGb: 10 });
const sandbox = await Sandbox.create('base', {
  projectId: 'proj_123', volumeName: 'agent-workdir',
});
try {
  await sandbox.fs.write('/workspace/state.json', JSON.stringify({ step: 1 }));
} finally {
  await sandbox.kill();
}
 
// A later sandbox mounts the same data by name.
const next = await Sandbox.create('base', {
  projectId: 'proj_123', volumeName: 'agent-workdir',
});
try {
  console.log(await next.fs.read('/workspace/state.json'));
} finally {
  await next.kill();
}
from lizard import Sandbox, Volume
 
Volume.get_or_create("proj_123", "agent-workdir", size_gb=10)
sandbox = Sandbox.create("base", project_id="proj_123", volume_name="agent-workdir")
try:
    sandbox.process.exec_("echo hello > /workspace/state.txt")
finally:
    sandbox.kill()

Tamaño y precio

Los volúmenes nuevos admiten 1 a 50 GB, en GB enteros, con 5 GB por defecto. El servidor puede cambiar el máximo mediante VOLUME_MAX_SIZE_GB; el panel y la CLI leen los límites actuales y el precio de almacenamiento de GET /api/projects/:projectId/volume-limits.

Pagas por el espacio usado, no por toda la capacidad asignada. Los volúmenes que superen el nuevo máximo mantienen su tamaño y siguen disponibles. Crear un volumen requiere suficiente espacio libre sin reservar en un nodo de trabajo sano de la región elegida. Si no hay espacio, la API devuelve 503 con el código volume_capacity_unavailable.

Gestionar volúmenes

await Volume.list('proj_123');
const volume = await Volume.get('proj_123', 'agent-workdir');
await volume.getInfo('proj_123');
await Volume.resize('proj_123', 'agent-workdir', 20);
await Volume.delete('proj_123', 'agent-workdir'); // detach first
TypeScriptPythonUso
Volume.getOrCreate(projectId, name, options)Volume.get_or_create(project_id, name, size_gb=5)Reutilizar un volumen o crearlo
Volume.create(projectId, name, options)Volume.create(project_id, name, size_gb=5)Crear; fallar si el nombre ya existe
Volume.list(projectId)Volume.list(project_id)Listar los volúmenes del proyecto
Volume.get(projectId, nameOrId)Volume.get(project_id, name_or_id)Buscar un volumen
Volume.resize(projectId, nameOrId, sizeGb)Volume.resize(project_id, name_or_id, size_gb)Cambiar el tamaño
Volume.delete(projectId, nameOrId)Volume.remove(project_id, name_or_id)Eliminar un volumen desconectado

Los ID generados y los campos volumeId / volume_id siguen funcionando. Usa nombres en el código nuevo.

El cambio de tamaño se aplica al volumen existente, también mientras el volumen está conectado. Un volumen Firecracker solo puede crecer. Un volumen basado en pods también puede reducirse si al menos el 10% del nuevo tamaño queda libre.

CLI

lizard volume create agent-workdir --size 10 --project proj_123
lizard volume list --project proj_123
lizard sandbox create --volume agent-workdir --project proj_123
lizard volume resize agent-workdir --size 20 --project proj_123
# After stopping the sandbox:
lizard volume rm agent-workdir --project proj_123

--size acepta GB enteros y comprueba el límite actual del servidor antes de crear el volumen. volume list muestra nombres; usa --json si necesitas los ID.

Panel de control

Crea y conecta volúmenes con el SDK o la CLI. Cuando un proyecto tiene un volumen, Sandboxes → Persistent Volumes muestra el espacio usado y asignado, el estado y el sandbox conectada. Desde ahí puedes explorar archivos, cambiar el tamaño de un volumen o eliminarlo.

Ciclo de vida del almacenamiento

  • Detener un sandbox o dejar que caduque desconecta su volumen y conserva los datos.
  • Un volumen conectado no puede conectarse a otro sandbox ni eliminarse.
  • Eliminar un volumen borra sus datos. Los volúmenes usan almacenamiento local del nodo; exporta los datos que necesites tras un fallo del nodo. Consulta almacenamiento y recuperación.
  • Sin volumen, /workspace es temporal: sus archivos desaparecen cuando el sandbox se detiene.
  • No se puede hacer fork de un sandbox con un volumen conectado (HTTP 409), y un snapshot no captura un volumen conectado.

Consulta las opciones de Sandboxes en la referencia del SDK y el ciclo de vida para la pausa, los snapshots y fork.

Ejecutar OpenCodePanel

Actualizado