Persistent Volumes

Persistent volumes are workspace-scoped block storage that survives the session it was used in. Volumes are the right tool for durable data: package caches, build caches, large repos, datasets, anything you want available across many sessions.

Volume lifecycle

Pick your tool, and the selection syncs across the rest of the page.

Create

import { GiB } from "@tenkicloud/sandbox";

const volume = await sandbox.createVolume({
  name: "data-vol",
  sizeBytes: 10 * GiB,
});

await sandbox.waitVolumeReady(volume.id);

Volumes can be between 1 MiB and 50 GiB.

List, get, resize, delete

const volumes = await sandbox.listVolumes();
const volume = await sandbox.getVolume(volumeId);
await sandbox.resizeVolume(volumeId, 40 * GiB);
await sandbox.deleteVolume(volumeId);

Attach to sessions

Attach at create time

const session = await sandbox.createAndWait({
  volumes: [
    { volumeId: cacheVolumeId, mountPath: "/workspace/cache" },
    { volumeId: refVolumeId, mountPath: "/workspace/reference", readOnly: true },
  ],
});

Attach to a running session

await session.attachVolume(volume.id, "/mnt/data");
await session.detachVolume(volume.id);

Workspace scope

Volumes belong to the workspace bound to your API key. Create and list calls infer that workspace, so do not pass a workspace ID.

Snapshots and volumes

Snapshots do not auto-reattach a session's volumes. A restored session is a normal session, so reattach any volume explicitly, at create time or with volume attach. See Snapshots for the restore workflow.

Keep durable data in volumes, not snapshots: baking a cache or dataset into a snapshot bloats it and ties that data to one VM's history.

Errors to handle

Volume calls can fail with a not-found, in-use, or quota error. The one worth handling is in-use: the volume is still attached to another session, so detach it from that session or wait, then retry. Every SDK surfaces these as typed errors or exceptions; see the SDK reference for the names in each language.