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 un solo sandbox a la vez. El 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. Los volúmenes de un workspace pueden sumar hasta 200 GB de tamaño asignado; crear o redimensionar un volumen por encima de eso devuelve 403 con el código volume_quota_exceeded.

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.

Volume.resize hace crecer un volumen sin moverlo. Un sandbox que tiene el volumen conectado sigue en marcha, pero aún ve el tamaño anterior; el siguiente sandbox que conecte el volumen ve el nuevo. Un volumen solo puede crecer. Algunos volúmenes creados antes de octubre de 2026 también pueden 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. La página Volumes de la barra lateral del panel muestra el espacio usado y asignado de cada volumen, su estado y el sandbox conectado. 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 forma parte del disco del sandbox: una pausa o un snapshot conserva sus archivos, y un kill o la expiración los borra.
  • No se puede hacer fork de un sandbox con un volumen conectado (HTTP 409).
  • Un snapshot de un sandbox con un volumen conectado incluye una copia de los archivos del volumen tal como estaban al capturar. Cada restauración recibe esa copia, no el volumen real, y no puede conectar otro volumen. Cualquiera que pueda restaurar el snapshot puede leer esos archivos; consulta snapshots.

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