<span id="persistent-volumes" />

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

<span id="create-and-attach-by-name" />

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

```ts
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();
}
```

```python
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()
```

<span id="size-and-price" />

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

<span id="manage-volumes" />

## Gestionar volúmenes

```ts
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.

<span id="cli" />

## CLI

```bash
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.

<span id="dashboard" />

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

<span id="storage-lifecycle" />

## 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](https://lizard.build/es/docs/platform/storage-and-recovery).

Consulta las opciones de Sandbox en la [referencia del SDK](https://lizard.build/es/docs/sandboxes/sdk-reference).