Persistent Volumes

Un volumen en Lizard (lizard.build) conserva los datos cuando una Sandbox se detiene. Se monta en /workspace y se conecta a una sola 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–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 de GET /api/projects/:projectId/volume-limits. El panel también lee el precio de almacenamiento de ese endpoint y lo muestra bajo el control de tamaño.

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.delete('proj_123', 'agent-workdir'); // detach first

TypeScript	Python	Uso
`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.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.

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
# 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

Abre Sandboxes → Volumes en un proyecto. El formulario comprueba el nombre y ofrece un control de tamaño con el máximo y el precio actuales. La lista muestra el espacio usado y asignado, el estado y la Sandbox conectada. Puedes copiar el ID desde los detalles del volumen.

Ciclo de vida del almacenamiento

Detener una Sandbox o dejar que caduque desconecta su volumen y conserva los datos.
Un volumen conectado no puede conectarse a otra Sandbox ni eliminarse.
Una Sandbox en pausa mantiene su conexión.
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.

Consulta las opciones de Sandbox en la referencia del SDK.

Intérprete de código Panel