<span id="persistent-volumes" />

# Persistent Volumes

Ein Volume in Lizard (lizard.build) behält Daten, nachdem eine Sandbox stoppt. Es wird unter **`/workspace`** eingebunden und kann mit **einer Sandbox gleichzeitig** verbunden sein. Die Sandbox läuft auf demselben Knoten wie ihr Volume.

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

## Nach Namen erstellen und verbinden

Namen sind innerhalb eines Projekts eindeutig. Verwende Kleinbuchstaben, Ziffern und Bindestriche, bis zu 64 Zeichen. Der Name muss mit einem Buchstaben oder einer Ziffer beginnen und enden.

Mit `getOrCreate` kannst du ein Volume mit Namen erneut nutzen. Die Größe gilt nur beim Erstellen eines neuen Volumes; die Größe eines bestehenden Volumes ändert sich nie. `Volume.create` meldet einen Konflikt, wenn der Name vergeben ist.

```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" />

## Größe und Preis

Neue Volumes erlauben **1–50 GB** in ganzen GB, mit **5 GB** als Standard. Der Server kann den Höchstwert über `VOLUME_MAX_SIZE_GB` ändern. Dashboard und CLI lesen die aktuellen Grenzen aus `GET /api/projects/:projectId/volume-limits`. Das Dashboard liest auch den Speicherpreis von diesem Endpunkt und zeigt ihn unter dem Größenregler.

Du zahlst für **belegten Speicher**, nicht für die gesamte zugewiesene Kapazität. Bestehende Volumes über dem neuen Höchstwert behalten ihre Größe und bleiben erreichbar. Ein neues Volume braucht genug freien, nicht reservierten Speicher auf einem gesunden Worker der gewählten Region. Wenn kein Platz vorhanden ist, liefert die API `503` mit dem Code `volume_capacity_unavailable`.

<span id="manage-volumes" />

## Volumes verwalten

```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 | Zweck |
|---|---|---|
| `Volume.getOrCreate(projectId, name, options)` | `Volume.get_or_create(project_id, name, size_gb=5)` | Volume erneut nutzen oder erstellen |
| `Volume.create(projectId, name, options)` | `Volume.create(project_id, name, size_gb=5)` | Erstellen; Fehler bei vergebenem Namen |
| `Volume.list(projectId)` | `Volume.list(project_id)` | Volumes des Projekts auflisten |
| `Volume.get(projectId, nameOrId)` | `Volume.get(project_id, name_or_id)` | Volume suchen |
| `Volume.delete(projectId, nameOrId)` | `Volume.remove(project_id, name_or_id)` | Getrenntes Volume löschen |

Erzeugte IDs und die Felder `volumeId` / `volume_id` funktionieren weiterhin. Nutze Namen in neuem Code.

<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` akzeptiert ganze GB und prüft vor dem Erstellen die aktuelle Servergrenze. `volume list` zeigt Namen; für IDs nutze `--json`.

<span id="dashboard" />

## Dashboard

Öffne **Sandboxes → Volumes** in einem Projekt. Das Formular prüft den Namen und bietet einen Größenregler mit dem aktuellen Höchstwert und Preis. Die Liste zeigt belegten und zugewiesenen Speicher, Status und verbundene Sandbox. Die ID kannst du bei Bedarf aus den Volume-Details kopieren.

<span id="storage-lifecycle" />

## Lebenszyklus des Speichers

- Das Stoppen oder Ablaufen einer Sandbox trennt ihr Volume und behält die Daten.
- Ein verbundenes Volume kann weder mit einer anderen Sandbox verbunden noch gelöscht werden.
- Eine pausierte Sandbox behält ihre Verbindung.
- Das Löschen eines Volumes entfernt seine Daten. Volumes nutzen lokalen Speicher des Knotens; exportiere Daten, die du nach einem Knotenausfall brauchst. Siehe [Speicherung und Wiederherstellung](https://lizard.build/de/docs/platform/storage-and-recovery).

Sandbox-Optionen stehen in der [SDK-Referenz](https://lizard.build/de/docs/sandboxes/sdk-reference).