<span id="persistent-volumes" />

# Persistent Volumes

Том в Lizard (lizard.build) хранит данные после остановки Sandbox. Он подключается в **`/workspace`**, к **одной Sandbox за раз**. Sandbox работает на том же узле, что и том.

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

## Создание и подключение по имени

Имена уникальны в пределах проекта. Используйте строчные латинские буквы, цифры и дефисы, до 64 символов. Имя должно начинаться и заканчиваться буквой или цифрой.

Чтобы повторно использовать том с заданным именем, вызовите `getOrCreate`. Размер действует только при создании нового тома; метод не меняет размер существующего. `Volume.create` возвращает конфликт, если имя занято.

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

## Размер и цена

Новые тома допускают **1–50 GB**, только целые GB, по умолчанию **5 GB**. Сервер может менять предел через `VOLUME_MAX_SIZE_GB`; панель управления и CLI читают текущие ограничения из `GET /api/projects/:projectId/volume-limits`. Панель также читает цену хранения из этого запроса и показывает её под ползунком размера.

Вы платите за **занятое место**, а не за весь выделенный объём. Существующие тома больше нового предела сохраняют размер и остаются доступны. Для нового тома нужно достаточно свободного, ещё не зарезервированного места на исправном рабочем узле выбранного региона. Если места нет, API возвращает `503` с кодом `volume_capacity_unavailable`.

<span id="manage-volumes" />

## Управление томами

```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 | Назначение |
|---|---|---|
| `Volume.getOrCreate(projectId, name, options)` | `Volume.get_or_create(project_id, name, size_gb=5)` | Использовать том или создать его |
| `Volume.create(projectId, name, options)` | `Volume.create(project_id, name, size_gb=5)` | Создать; вернуть ошибку, если имя занято |
| `Volume.list(projectId)` | `Volume.list(project_id)` | Список томов проекта |
| `Volume.get(projectId, nameOrId)` | `Volume.get(project_id, name_or_id)` | Найти том |
| `Volume.delete(projectId, nameOrId)` | `Volume.remove(project_id, name_or_id)` | Удалить отключённый том |

Сгенерированные ID и поля `volumeId` / `volume_id` по-прежнему работают. В новом коде используйте имена.

<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` принимает целые GB и проверяет текущий предел сервера до создания тома. `volume list` показывает имена; для ID используйте `--json`.

<span id="dashboard" />

## Панель управления

Откройте **Sandboxes → Volumes** в проекте. Форма создания проверяет имя и предлагает ползунок размера с текущим пределом и ценой. Список показывает занятое и выделенное место, статус и подключённую Sandbox. При необходимости скопируйте ID из сведений о томе.

<span id="storage-lifecycle" />

## Жизненный цикл хранения

- Остановка Sandbox или истечение её срока отключает том и сохраняет данные.
- Подключённый том нельзя подключить к другой Sandbox или удалить.
- Приостановленная Sandbox сохраняет подключение.
- Удаление тома удаляет его данные. Тома хранят данные на узле; экспортируйте данные, которые нужны после отказа узла. См. [хранение и восстановление](https://lizard.build/ru/docs/platform/storage-and-recovery).

Параметры Sandbox описаны в [справочнике SDK](https://lizard.build/ru/docs/sandboxes/sdk-reference).