<span id="persistent-volumes" />

# Persistent Volumes

Lizard (lizard.build) のボリュームは、Sandbox の停止後もデータを保持します。**`/workspace`** にマウントされ、**同時に接続できる Sandbox は1つ**です。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** の整数で、既定値は **5 GB** です。サーバーは `VOLUME_MAX_SIZE_GB` で上限を変更できます。ダッシュボードと CLI は `GET /api/projects/:projectId/volume-limits` から現在の制限を取得します。ダッシュボードは同じエンドポイントから保存料金も取得し、容量スライダーの下に表示します。

課金対象は割り当てた容量全体ではなく、**使用中の容量**です。新しい上限を超える既存のボリュームは、サイズを維持したまま使えます。新規作成には、選んだリージョンの正常なワーカーに十分な未予約の空き容量が必要です。空き容量がない場合、API はコード `volume_capacity_unavailable` とともに `503` を返します。

<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/ja/docs/platform/storage-and-recovery)を参照してください。

Sandbox のオプションは [SDK リファレンス](https://lizard.build/ja/docs/sandboxes/sdk-reference)を参照してください。