Setup snapshots

On the first call to Alineo.start(), the SDK installs the Pi CLI inside a node:22 sandbox, runs any workspace setup steps, 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's job.

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

fromSnapshot

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

// 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

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

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

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

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.