SandboxesPersistent Volumes

Persistent Volumes

Persistent Volumes keep data after a sandbox stops. Each volume mounts at /workspace and attaches to one sandbox at a time. The sandbox runs on the same node as its volume.

Create and attach by name

Names are unique within a project. Use lowercase letters, digits and dashes, starting and ending with a letter or digit, up to 64 characters.

Use getOrCreate to reuse a named volume. Its size applies only when creating a new volume; it never resizes an existing one. Volume.create returns a conflict if the name is taken.

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

Size and price

New volumes allow 1 to 50 GB, in whole GB, with 5 GB as the default. The server can override the maximum through VOLUME_MAX_SIZE_GB; the dashboard and CLI read the current limits and storage price from GET /api/projects/:projectId/volume-limits.

You pay for used space, not the full allocation. Existing volumes larger than the new maximum keep their size and remain accessible. The volumes of one workspace can add up to 200 GB of allocated size; a create or resize past that returns 403 with code volume_quota_exceeded.

Manage volumes

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
TypeScriptPythonPurpose
Volume.getOrCreate(projectId, name, options)Volume.get_or_create(project_id, name, size_gb=5)Reuse a volume or create it
Volume.create(projectId, name, options)Volume.create(project_id, name, size_gb=5)Create; fail if the name is taken
Volume.list(projectId)Volume.list(project_id)List the project’s volumes
Volume.get(projectId, nameOrId)Volume.get(project_id, name_or_id)Look up a volume
Volume.resize(projectId, nameOrId, sizeGb)Volume.resize(project_id, name_or_id, size_gb)Change the size
Volume.delete(projectId, nameOrId)Volume.remove(project_id, name_or_id)Delete a detached volume

Generated IDs and the volumeId / volume_id fields still work for existing callers. Use names in new code.

Volume.resize grows a volume in place. A sandbox that has the volume attached keeps running but still sees the old size; the next sandbox that attaches the volume sees the new one. A volume can only grow. Some volumes created before October 2026 can also shrink if at least 10% of the new size stays free.

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 accepts whole GB and checks the current server limit before creating a volume. volume list shows names; use --json when you need IDs.

Dashboard

Create and attach volumes with the SDK or CLI. The Volumes page in the dashboard sidebar lists each volume’s used and allocated space, status, and attached sandbox. From there you can browse files, resize, or delete a volume.

Storage lifecycle

  • Killing or expiring a sandbox detaches its volume and keeps the data.

  • An attached volume cannot attach to another sandbox or be deleted.

  • Deleting a volume removes its data. Volumes use node-local storage; export data you need after a node failure. See storage and recovery.

  • Without a volume, /workspace is part of the sandbox’s disk: a pause or a snapshot keeps its files, and a kill or expiration deletes them.

  • A sandbox with a volume attached cannot be forked (HTTP 409).

  • A snapshot of a sandbox with a volume attached includes a copy of the volume’s files as they were at capture. Every restore gets that copy, not the live volume, and cannot attach another volume. Anyone who can restore the snapshot can read those files; see snapshots.

See the SDK reference for sandbox options and lifecycle for pause, snapshots and fork.

Run OpenCodeDashboard

Updated