Snapshots carry the deployment.

2026-10-01 · by Dennis Gubsky · snapshots arc · ~8 min read

A loomcycle snapshot used to be a transcript. Not literally one file per conversation, but close: an archive of recent sessions, their messages, their tool calls, their tool results. If you took a snapshot and restored it on a different machine, you got the chat history back. Everything else that made the first machine a working deployment was your problem to reproduce.

That was fine when loomcycle was small enough to re-set-up in an afternoon. It stopped being fine the first time a self-hoster asked how to move a working deployment to a new VM without losing a day to reconfiguration.

v1.101 shipped the fix in 127 pull requests under one release.

What a snapshot used to carry

Agents (as definitions). Skills. Teams. Memory backends by configuration pointer. Document sources by configuration pointer. Session transcripts.

That is a useful set for a disaster-recovery scenario where the deployment metadata lives in config files on disk and only the runtime state needs to be rescued. It is not a useful set for a move-this-deployment scenario where you want to point a new machine at an old snapshot and have it come back as the same deployment.

What a snapshot carries now

The list grew to cover everything a working deployment is made of.

• Users and budgets. Every user in the tenant, their roles, their per-user token and dollar budgets, their current usage. A snapshot taken mid-month restores the users at their mid-month spend; no surprise re-mint of allowances.
• Schedules. Every cron entry, with its concurrency policy, catch-up config, and last-run cursor. A restored schedule picks up where it left off (or skips forward to now, if the catch-up policy says so).
• Webhooks. Every inbound webhook endpoint, with its HMAC-signed secret (as an opaque reference, not the literal secret) and its target.
• Memory peers. Every kind: remote memory backend the deployment proxies to.
• Document sources. Every peer loomcycle the deployment federates documents with.
• Volume mounts. The volume topology (which agents mount which volumes at which paths).
• Path tree. The whole dirent/inode structure the user built up.
• Consolidation queue. Pending-but-not-yet-consolidated memory writes. A restored deployment resumes consolidation where it stopped.

What a snapshot deliberately does not carry

Three things, by decision.

Literal trigger credentials. A snapshot carries the reference to each credential (the api_key_env name and the credential-def id) but never the value. On restore, the credential-def pointers resolve against the new machine's environment variables. A snapshot moved between machines will reach for its credentials in the new environment; if they are not there, the restore flags them and the affected integrations stay inert until the operator points them at the new secrets. The alternative, writing literal secrets to the archive, is the attack path the archive would become.

In-flight run state. A snapshot carries completed sessions and parked interactive runs. It does not carry an actively-running run's internal LLM state (the current turn's context, the model's partial generation, the sub-agents it has in flight). Restoring a snapshot while a run is in flight does not resume that run; it ends on the source machine. Live runs are a transcript concern, not a deployment concern.

Replica-local caches. Prompt caches, response caches, any ephemeral state that is "we can rebuild this." On restore the deployment comes back cold on those caches. Not an operational problem; worth knowing on the first restore so a one-time latency bump does not look like a regression.

Restore re-checks everything

A snapshot that loads cleanly tells you the deployment matches the runtime version. A snapshot that does not load cleanly tells you specifically what is wrong, before the deployment starts serving traffic.

Restore re-validates every definition against the current runtime schema. An agent def that used a config field removed in a later release gets flagged with the field name and the version it was removed in. A schedule using a cron syntax the current runtime no longer accepts gets flagged with the specific entry. A webhook pointing at a credential-def that does not resolve in the new environment gets flagged with the credential name.

The restore operation can either refuse (an operator must fix the flagged items and retry) or restore in degraded mode (the clean items come back, the flagged items are quarantined for the operator to fix). The default is refuse; degraded mode is a flag the operator sets when they know what they are doing.

The security review folded in

127 PRs is a lot. A chunk of them are an adjacent security review that closed cross-tenant and isolated-member gaps in the surfaces that a snapshot carries.

Webhooks. A webhook callback could reach a private address if the tenant's URL allowlist was wider than it should be. The SSRF guard now runs on every webhook target at config time, not just at call time, so a misconfiguration refuses at save instead of at first fire.

Triggers. A tenant trigger (schedule, webhook, remote peer) could, in some combinations, reach cross-tenant data through a shared-code path. The code paths are now tenant-isolated at each entry.

Remote peers. A kind: remote memory backend could, in some combinations, hand an isolated member of one tenant visibility into another tenant's addresses. The visibility is now gated at the peer-resolution layer.

Volume paths. A volume mount at a resolved path could escape its declared root in certain traversal paths. The root is now re-enforced on every file op, not just on mount.

These are the kind of fixes you want in a release that explicitly ships "the deployment moves atomically" as a feature, because an archive that moves is an archive that can be mistargeted on restore, and a cross-tenant leak at that moment would be hard to recover from.

What this does not fix

Three limits.

Snapshots are not versioned incrementally. A snapshot is a full archive, not a diff from the previous one. Taking frequent snapshots is cheap in time but not in storage. A deployment with 100GB of document chunks produces 100GB snapshots. Compaction between snapshots is on the roadmap.

Cross-version restore has limits. A snapshot taken on v1.101 restores cleanly on v1.102 through v1.108. A snapshot taken on a pre-v1.101 release does not have the whole-deployment contents; restoring it on v1.101+ gives you the old shape (transcripts and defs, no users/budgets/schedules/webhooks). That is the expected migration path, not a bug.

The consolidation queue restores but does not re-order. If the queue was in a specific order on the source (prioritised, cursor-held), it comes back in snapshot-write order on the target. The consolidator picks up from the same cursor and reaches the same end state; the intermediate ordering can differ for a short window.

What this makes possible

A self-hoster migrating from one VM to another writes loomcycle snapshot create on the old machine, moves the archive, and runs loomcycle snapshot restore on the new one. The whole deployment comes back: the users have their budgets, the schedules fire on their cadence, the webhooks are at their URLs, the peers are reachable, the volumes mount at their declared paths. The only operator work is pointing the new machine's environment at the right secrets.

A test harness that spins up a snapshotted "golden" tenant for each test and tears it down afterwards used to be impractical (too much setup); it is now a one-call restore and a one-call teardown.

A pre-production deployment can be snapshotted from production, loaded on staging, and run with real-shape data without manual reproduction.

What comes next

Incremental snapshots (diffs from a baseline) are the next step for the storage-cost gap. Cross-version restore guidance will land as a documented matrix once the migration patterns stabilise. The security review is going to run on a quarterly cadence from here on; the surfaces that moved in October's team-ergonomics arc (local agents and schedules inside a team file) will see the next pass.