Volume lifecycle

Create, list, check existence, and delete named volumes.

You usually don’t need to call these — referencing a volume in LaunchOptions.mounts auto-creates it with defaults. Reach for these helpers when you want quotas, labels, or explicit cleanup.

ensureVolume(name, opts?) → Promise<void>

Create a volume if it doesn’t already exist. Idempotent — safe to call from scripts that re-run.

import { ensureVolume } from "@beamhop/lightbox";

await ensureVolume("npm-cache", {
  quotaMib: 4096,
  labels: { team: "platform", purpose: "ci-cache" },
});

EnsureVolumeOptions

listVolumes() → Promise<VolumeRecord[]>

Enumerate every named volume.

import { listVolumes } from "@beamhop/lightbox";

for (const v of await listVolumes()) {
  console.log(v.name, v.quotaMib, v.usedBytes, v.labels);
}

VolumeRecord

interface VolumeRecord {
  name: string;
  quotaMib: number | null;
  usedBytes: number;
  labels: Record<string, string>;
  createdAt: Date | null;
}

volumeExists(name) → Promise<boolean>

Shortcut for “is this volume here?”.

import { volumeExists } from "@beamhop/lightbox";

if (await volumeExists("npm-cache")) { ... }

removeVolume(name) → Promise<void>

Delete a named volume. Idempotent — silent if it doesn’t exist. Deletes the volume’s contents.

import { removeVolume } from "@beamhop/lightbox";

await removeVolume("npm-cache");