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

# Snapshots

> Put the setup every box of a repo shares in a snapshot file, so new boxes start with it already done

Installing a repo's dependencies is usually the slowest part of starting a
box. A snapshot file holds the setup that every box of the repo shares, such
as the workspace install. Tesser captures a box's disk right after that
setup runs, and new boxes start from the capture, so their installs only
catch up on what changed since.

## Write a snapshot file

Put the shared setup in `default.snapshot.toml` beside the manifests:

```toml theme={"theme":"css-variables"}
# .agents/skills/tesser/default.snapshot.toml
setup = "pnpm install"
```

Every manifest in the repo and every workbench of the repo takes
`default.snapshot.toml`. A manifest's own `setup` then holds only what its
service needs on top, and you can leave it out when there is nothing more:

```toml theme={"theme":"css-variables"}
# .agents/skills/tesser/web.toml
ports = [3000]

[run]
dev = "pnpm dev"
```

Every start runs the snapshot file's `setup`, then the manifest's `setup`,
then `dev`. On a box that started from a snapshot, the install finds almost
everything in place and finishes quickly.

The disk this `setup` leaves behind is shared with every box that starts
from it, including teammates' boxes. Keep anything specific to one box, such
as its address or a per-box secret, in the manifest's `setup` or `dev`.

## Give a service its own snapshot

A service that needs a different base names another snapshot file with
`from_snapshot`:

```toml theme={"theme":"css-variables"}
# .agents/skills/tesser/api.toml
ports = [8080]
from_snapshot = "api"        # starts from api.snapshot.toml

[run]
dev = "pnpm dev"
```

## How snapshots are made

You don't build snapshots by hand. The first box that starts blank at a
commit runs the snapshot file's `setup` and captures its disk the moment
that `setup` finishes, before the manifest's `setup`, `dev`, or anyone else
touches the box. The run carries on while the capture finishes in the
background. Boxes that start from a snapshot never make one.

A new box starts from the snapshot nearest its commit, so a box a few
commits ahead of the snapshot still starts warm.

To make the snapshots a commit is missing now, and wait for them:

```sh theme={"theme":"css-variables"}
tesser snapshot create                 # at HEAD
tesser snapshot create --sha <commit>  # at another commit
```

Running `tesser snapshot create` from CI on every push to your default
branch keeps a fresh snapshot waiting for everyone. [Agents and
CI](https://tesser.sh/docs/teams.md#agents-and-ci) covers how CI signs in.

## Look at and manage snapshots

```sh theme={"theme":"css-variables"}
tesser snapshot ls                     # this repo's snapshots, newest first
tesser status <box_id>                 # the snapshot a box started from
tesser make --snapshot <snapshot_id>   # a new box from a specific snapshot
tesser make --no-snapshot              # a new box that starts blank
tesser snapshot rm <snapshot_id>       # remove one; its boxes keep running
```

Tesser keeps the newest snapshot of each name on each branch and deletes old
ones on its own.

[Snapshot files](https://tesser.sh/docs/manifest.md#snapshot-files) lists every field of the file,
and [Snapshots](https://tesser.sh/docs/reference/boxes.md#snapshots) has the exact rules for which
snapshot a box picks, when a box captures one, and how long snapshots are
kept.


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