Volumes & mounts

Bind-mount host directories and attach named volumes to sandboxes.

Mounts let a sandbox see data that isn’t in its snapshot: a directory on the host, or a persistent named volume that survives across sandbox lifecycles.

If you know Docker volumes / bind-mounts, this is the same idea — same syntax shape, same use cases.

Mount syntax

Declared per-launch on LaunchOptions.mounts, keyed by guest path:

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

const sb = await launchSandbox({
  snapshot: "node-ci",
  name: "ci-run-1",
  mounts: {
    "/work":  "./my-project",            // string → bind-mount a host directory
    "/cache": { volume: "npm-cache" },   // object → named volume (auto-created)
  },
});

type Mount =
  | string                  // bind-mount: host path → guest path
  | { volume: string };     // named volume (created on demand if absent)

Bind mounts

A string value bind-mounts a host directory at the guest path. Writes from the guest appear on the host. Useful for shipping local source code into a sandbox without baking it into the snapshot.

mounts: { "/work": "./my-project" }

The host path must exist before launch — the SDK doesn’t auto-create it. The guest path must not collide with files already present in the snapshot; use a fresh directory (/work, /mnt/...) or mkdir -p it in the snapshot’s setup steps.

Named volumes

An object value { volume: name } mounts a named, persistent volume. It survives sandbox restarts and can be mounted into many sandboxes at once — ideal for package caches, model weights, build artifacts shared across jobs.

mounts: { "/root/.npm": { volume: "npm-cache" } }

Volumes are auto-created on first use with default settings. If you need a quota or labels, create the volume explicitly with ensureVolume() before launching — that helper is idempotent so it’s safe in startup scripts.

Pages

• Lifecycle — ensureVolume, listVolumes, volumeExists, removeVolume