# Setup snapshots
URL: /docs/agent/concepts/snapshots

How Alineo.start() caches the Pi install and your setup steps, so every start after the first takes seconds instead of minutes.



On the first call to `Alineo.start()`, the SDK installs the Pi CLI inside a `node:22` sandbox, runs any [workspace setup steps](/docs/agent/concepts/workspace-setup), then snapshots the container — the **setup snapshot**. On every subsequent call it restores from that snapshot — skipping the install entirely.

A setup snapshot holds an installed environment, not a conversation: every agent restored from it starts empty. Bringing one particular agent back to its last turn is a [turn checkpoint](/docs/agent/concepts/reconnecting#turn-checkpoints)'s job.

```
Load 1 (cold):   sandbox → Pi install → setup steps → snapshot → bridge     ~90s
Load 2+ (warm):  snapshot restore → bridge                                   ~3s
```

## fromSnapshot [#fromsnapshot]

`agent.fromSnapshot` is `true` when the agent was restored from a snapshot:

```ts
// adapter: an IStorageAdapter — SQLiteAdapter or PostgresAdapter, see Quickstart
const spec = await Bun.file("./agents/my-agent.json").json();
const agent = await Alineo.start(spec, { adapter });
console.log(agent.fromSnapshot); // false on first load, true after
```

## Cache invalidation [#cache-invalidation]

The snapshot is keyed on a hash of the fields that affect the installed environment:

* `harness` — currently always `"pi"`
* `harnessVersion` — pinned version or `"latest"`
* `packages` — APT packages sorted alphabetically
* `setup` — workspace setup steps (names, commands, working directories)

Any change to these fields automatically invalidates the snapshot and triggers a full rebuild on the next `Alineo.start()` call. Fields that don't affect the snapshot — `model`, `provider`, `env`, `resources` — never invalidate the cache.

## Force rebuild [#force-rebuild]

Pass `{ rebuild: true }` to force a full reinstall regardless of the cached snapshot:

```ts
const agent = await Alineo.start(spec, { adapter, rebuild: true });
```

This is useful after updating a package version that isn't tracked through the spec (e.g. a package installed by a setup step that fetches from the internet).

## How the snapshot store works [#how-the-snapshot-store-works]

Snapshot records are stored in `agent-snapshots.json` alongside the ledger database (`.alineo/agent-snapshots.json` by default). Each record maps `specName + setupHash` → `snapshotId`. On restore, `client.restoreSnapshot(snapshotId)` recreates the container from the saved image.

If the snapshot no longer exists on the OpenSandbox server (e.g. after a server restart), `Alineo.start()` detects the failure, logs a `warn` (`snapshot restore failed, rebuilding`, with the underlying `reason`), and falls back to a full install automatically.