Snapshots

A snapshot captures the filesystem state of a sandbox so it can be restored on the next start. Snapshots are configured in SandboxConfig.snapshot and work automatically: Hive saves a snapshot when the sandbox shuts down and restores it before the next run, giving you persistent state across restarts without managing files manually.

How snapshots work

When a sandbox starts, Hive checks for a snapshot at restore_key. If one exists, the included paths are restored before any process runs. When the sandbox shuts down, Hive saves a new snapshot to write_key covering the paths matched by include.

If restore_key does not exist yet — for example on the very first run — the sandbox starts fresh and the snapshot is written at shutdown. Every subsequent start restores from that point.

Basic usage

import { getOrCreateSandbox } from "hive";

const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
  snapshot: {
    restore_key: "my-snapshot",  // restore from this key on start
    write_key: "my-snapshot",    // save to this key on shutdown
    include: ["/workspace/**"],  // paths to capture
  },
});

import { getOrCreateSandbox } from "hive";

const sandbox = await getOrCreateSandbox("my-sandbox", {
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
  snapshot: {
    restore_key: "my-snapshot",  // restore from this key on start
    write_key: "my-snapshot",    // save to this key on shutdown
    include: ["/workspace/**"],  // paths to capture
  },
});

On the first run my-snapshot does not exist, so the sandbox starts fresh. On shutdown Hive writes the snapshot. Every subsequent run restores from my-snapshot before anything executes.

write_key defaults to restore_key when omitted, so the two-line form is equivalent:

snapshot: {
  restore_key: "my-snapshot",
  include: ["/workspace/**"],
},

snapshot: {
  restore_key: "my-snapshot",
  include: ["/workspace/**"],
},

Key IDs must match /^[A-Za-z0-9_-]{1,64}$/.

Branching pattern

Restore from one key and write to a different key to branch a baseline into parallel workstreams without mutating the original snapshot:

const branchSandbox = await getOrCreateSandbox("branch-a", {
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
  snapshot: {
    restore_key: "baseline",     // start from the shared baseline
    write_key: "branch-a-out",  // save changes to a separate key
    include: ["/workspace/**"],
  },
});

const branchSandbox = await getOrCreateSandbox("branch-a", {
  fs: [{ backend: "local", mount: "/workspace", acls: [{ path: "/workspace/**", access: "rw" }] }],
  snapshot: {
    restore_key: "baseline",     // start from the shared baseline
    write_key: "branch-a-out",  // save changes to a separate key
    include: ["/workspace/**"],
  },
});

baseline is never overwritten. You can spin up as many branches as you need — each restores from the same starting point and writes to its own key.

A common pattern for session-scoped state is to key the snapshot on a session identifier:

const snapshot = {
  restore_key: `session-${sessionId}`,
  write_key: `session-${sessionId}`,
  include: ["/workspace/**", "/home/user/.config/**"],
};

const snapshot = {
  restore_key: `session-${sessionId}`,
  write_key: `session-${sessionId}`,
  include: ["/workspace/**", "/home/user/.config/**"],
};

Each session gets its own isolated snapshot that accumulates changes over multiple restarts.

What to include

The include field is a list of glob patterns. Only paths that match at least one pattern are captured and restored.

Keep include as narrow as practical. Capturing large directories that change frequently (build caches, package downloads) increases snapshot size and restore time without benefit. Snapshot only the paths your agent actually produces and needs to resume from.

Next: Audit Log