Persistent Volumes

Lizard (lizard.build) のボリュームは、sandbox の停止後もデータを保持します。/workspace にマウントされ、同時に接続できる sandbox は1つです。sandbox はボリュームと同じノードで動作します。

名前で作成して接続する

名前はプロジェクト内で一意である必要があります。小文字の英字、数字、ハイフンを使い、64文字以内にします。先頭と末尾は英字または数字にしてください。

名前付きボリュームを再利用するには getOrCreate を使います。サイズ指定は新規作成時にのみ適用され、既存のボリュームのサイズは変更しません。名前が使用済みの場合、Volume.create は競合エラーを返します。

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

容量と料金

新しいボリュームの容量は 1〜50 GB の整数で、既定値は 5 GB です。サーバーは VOLUME_MAX_SIZE_GB で上限を変更できます。ダッシュボードと CLI は GET /api/projects/:projectId/volume-limits から現在の制限と保存料金を取得します。

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

ボリュームを管理する

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

生成された ID と volumeId / volume_id フィールドも引き続き使えます。新しいコードでは名前を使ってください。

サイズ変更はその場で行われ、ボリュームの接続中でも実行できます。Firecracker のボリュームは拡張のみできます。Pod ベースのボリュームは、新しいサイズの 10% 以上が空いたままになる場合に限り、縮小もできます。

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 は整数の GB を受け付け、作成前にサーバーの現在の上限を確認します。volume list は名前を表示します。ID が必要な場合は --json を使ってください。

ダッシュボード

ボリュームの作成と接続は SDK または CLI で行います。プロジェクトにボリュームがあると、Sandboxes → Persistent Volumes に使用量、割り当て容量、状態、接続先の sandbox が表示されます。そこからファイルの参照、サイズ変更、ボリュームの削除ができます。

ストレージのライフサイクル

• sandbox を停止するか有効期限が切れると、ボリュームを切断し、データを保持します。
• 接続中のボリュームは、別の sandbox に接続したり削除したりできません。
• ボリュームを削除するとデータも消えます。ボリュームはノードのローカルストレージを使うため、ノード障害後も必要なデータはエクスポートしてください。保存と復旧を参照してください。
• ボリュームがなければ /workspace は一時領域です: sandbox が停止するとそのファイルは消えます。
• ボリュームが接続された sandbox は fork できません（HTTP 409）。また、スナップショットには接続されたボリュームは含まれません。

sandbox のオプションは SDK リファレンスを、一時停止、スナップショット、fork については ライフサイクルを参照してください。

更新日 2026年10月12日