> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Prepared worktree snapshots

> Capture a clean committed project in prepared worktree snapshots and pin a ready snapshot for future starts.

Use prepared worktree snapshots to start worktrees with project dependencies and synthetic seed data already present. Build it from a clean local commit, then pin the ready snapshot in `bead.toml`.

## Build a snapshot

Run `bead worktree up` once, then commit the generated `project.name`, `prepare.run` and its inputs in `bead.toml`. The snapshot reads configuration from the selected commit. Use public dependencies and synthetic database seeds so preparation can run without credentials.

```bash theme={null}
bead worktree snapshot --commit HEAD
```

The commit must be locally available and clean. Laptop environment values are excluded. Wait for a ready snapshot ID before using it.

## Pin a prepared start

```toml theme={null}
[template]
id = "devbox"

[machine]
size = "medium"

[prepare]
run = "cargo fetch"
inputs = ["Cargo.lock", "Cargo.toml"]
snapshot = "YOUR_READY_SNAPSHOT_ID"
```

Use the ready snapshot returned by `bead worktree snapshot`, with its source commit available locally and matching project name, base template, machine size, `prepare.run` and sync include/exclude settings; rebuild when those settings change. Changed preparation inputs produce a stale warning; run `bead worktree prepare` to reconcile them.

If the worktree already has a bound machine, explicitly bring it down before starting with the changed configuration:

```bash theme={null}
bead worktree down
bead worktree up
bead worktree prepare
```

## Rebuild explicitly

Rebuild and update the pin when dependencies or setup change. Source sync does not implicitly install dependencies. Use `prepare` to reconcile project dependencies and schema.

A full-machine snapshot can retain a seeded local database. Each child has a private copy. Reconcile external connections and copied identity or random state in your project setup.

Prepared snapshots remain retained and billed separately after `worktree down`. Manage their lifetime with [snapshot commands](https://docs.bead.run/cli/templates-snapshots.md) and [snapshot retention](https://docs.bead.run/snapshots/retention.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.