SandboxesPersistent Volumes

Persistent Volumes

Ein Volume in Lizard (lizard.build) speichert Daten auch nach dem Stopp einer Sandbox. Es wird unter /workspace eingebunden und kann mit einer Sandbox gleichzeitig verbunden sein. Die Sandbox läuft auf demselben Knoten wie ihr Volume.

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; der Aufruf ändert die Größe eines bestehenden Volumes nicht. Volume.create meldet einen Konflikt, wenn der Name vergeben ist.

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

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 und den Speicherpreis aus GET /api/projects/:projectId/volume-limits.

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.

Volumes verwalten

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
TypeScriptPythonZweck
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.resize(projectId, nameOrId, sizeGb)Volume.resize(project_id, name_or_id, size_gb)Größe ändern
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.

Du kannst die Größe direkt am Volume ändern, auch während es verbunden ist. Ein Firecracker-Volume kann nur wachsen. Ein Pod-basiertes Volume kann auch schrumpfen, wenn mindestens 10 % der neuen Größe frei bleiben.

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

Dashboard

Erstelle und verbinde Volumes mit dem SDK oder der CLI. Sobald ein Projekt ein Volume hat, listet Sandboxes → Persistent Volumes belegten und zugewiesenen Speicher, Status und die verbundene Sandbox auf. Dort kannst du Dateien durchsuchen, die Größe ändern oder ein Volume löschen.

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.

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

  • Ohne Volume ist /workspace temporär: Seine Dateien sind weg, wenn die Sandbox stoppt.

  • Eine Sandbox mit verbundenem Volume kann nicht geforkt werden (HTTP 409), und ein Snapshot erfasst kein verbundenes Volume.

Sandbox-Optionen stehen in der SDK-Referenz, Pause, Snapshots und Fork im Lebenszyklus.

OpenCode ausführenDashboard

Aktualisiert