Types

Every public type exported by lightbox.

import type {
  SnapshotConfig,        // input to defineSnapshot / buildSnapshot
  PresetConfig,          // SnapshotConfig with guaranteed `setup`
  SetupStep,             // string | shell | exec
  SnapshotResources,     // { cpus?, memory? }
  BuildOptions,          // second arg to buildSnapshot
  LaunchOptions,         // arg to launchSandbox / runInSandbox
  Mount,                 // string (bind) | { volume: string } (named)
  SnapshotRecord,        // shape returned by listSnapshots()
  VolumeRecord,          // shape returned by listVolumes()
  EnsureVolumeOptions,   // second arg to ensureVolume()
  Memory,                // `${number}M` | `${number}G`
} from "@beamhop/lightbox";

Source

All types live in src/types.ts. Click through for the canonical definitions.

SnapshotConfig

interface SnapshotConfig {
  name: string;
  image: string;
  resources?: SnapshotResources;
  workdir?: string;
  env?: Record<string, string>;
  setup?: SetupStep[];
  labels?: Record<string, string>;
}

PresetConfig

interface PresetConfig extends SnapshotConfig {
  setup: SetupStep[]; // not optional — presets always define it
}

Returned by presets so callers can cfg.setup.push(...) without a non-null assertion.

SetupStep

type SetupStep =
  | string                                                              // shell shorthand
  | { kind: "shell"; script: string; description?: string }
  | { kind: "exec"; cmd: string; args?: string[]; description?: string };

The string form is sugar for { kind: "shell", script: <string> }. Use the object form when you want a description or kind: "exec".

SnapshotResources

interface SnapshotResources {
  cpus?: number;
  memory?: Memory; // "512M" | "2G" | ...
}
type Memory = `${number}M` | `${number}G`;

BuildOptions

interface BuildOptions {
  overwrite?: boolean;      // default: true
  debugBuilder?: boolean;   // default: false
  verbose?: boolean;        // default: false
}

LaunchOptions

interface LaunchOptions {
  snapshot: string;
  name: string;
  resources?: SnapshotResources;
  workdir?: string;
  env?: Record<string, string>;
  ports?: Record<number, number>;
  mounts?: Record<string, Mount>;  // keyed by guest path
  overwrite?: boolean;             // default: true
  verbose?: boolean;               // default: false
}

Mount

type Mount =
  | string                  // bind-mount a host directory at the guest path
  | { volume: string };     // named persistent volume (auto-created on first use)

VolumeRecord

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

EnsureVolumeOptions

interface EnsureVolumeOptions {
  quotaMib?: number;                    // only applied on initial creation
  labels?: Record<string, string>;      // only applied on initial creation
}

SnapshotRecord

interface SnapshotRecord {
  name: string | null;
  digest: string;
  imageRef: string;
  createdAt: Date;
  sizeBytes: bigint | null;
  path: string;
}