Snapshots

A WorkspaceSnapshot is a point-in-time copy of a Workspace's storage, i.e. its home directory, /workspace and its container layer, including every installed package, build artifact, dependency cache and uncommitted change. New Workspaces can be restored from a snapshot, which lets you:

Fork a fully set-up environment into many identical Workspaces, for example to run several AI agents in parallel on the same baseline or to shard a long test suite.
Checkpoint a Workspace before a risky operation (e.g. a major upgrade, a database migration or an autonomous agent run) and go back to it if anything goes wrong.
Share a reproducible state of a bug or an experiment as a new Workspace.

WorkspaceSnapshots are owned by the User who takes them, and they are backed by Kubernetes CSI volume snapshots, which means that taking and restoring them is fast and storage-efficient on backends that support copy-on-write snapshots (read more here).

Taking Snapshots

You can snapshot any of your Workspaces from the web portal, via the API, or via the CLI:

cordium create snapshot ledger-baseline --workspace k3x9

The snapshot is STATE_CREATING at first and becomes STATE_READY once the storage backend completes it. You can list and inspect your snapshots as follows:

cordium get snapshot
cordium get snapshot --workspace k3x9
cordium get snapshot ledger-baseline -o yaml

A snapshot's consistency depends on the state of its source Workspace:

CONSISTENCY_CLEAN snapshots are taken while the Workspace is stopped, and they contain exactly what was on disk when it stopped.
CONSISTENCY_CRASH snapshots are taken while the Workspace is running, and they are equivalent to the state of the disk after a power loss, i.e. data that was still buffered in memory by running processes (e.g. a database server) is not included.

note

For snapshots that you intend to fork many times, stop the Workspace first, or at least stop the stateful processes (e.g. databases) and run sync before taking the snapshot.

Keep the following in mind:

A Workspace can only have one snapshot that is being taken at a time.
A stopped ephemeral Workspace cannot be snapshotted, since its storage is discarded when it stops. Running ephemeral Workspaces can be snapshotted normally.
Template pre-build Workspaces cannot be snapshotted.
Mounted Volumes are not included in snapshots.
Every User can have up to 100 snapshots by default (read more here).

Restoring Snapshots

Restore a snapshot into a new Workspace as follows:

# Create a Workspace from a snapshot and start it
cordium create ws --snapshot ledger-baseline --start

# Or create, start and open a terminal in one step
cordium run --snapshot ledger-baseline

A restored Workspace belongs to the same Space and, unless you explicitly set another Template, to the same Template as the snapshot's source Workspace. It runs in the Region that holds the snapshot, and its storage is at least as large as the snapshot.

Since the restored storage already contains the result of the fresh-run work, a restored Workspace does not pull or build the image, clone the repositories, apply the dotfiles nor run the ON_CREATE tasks again. Its POST_START tasks, environment variables, network policy, Volume mounts and secretless access are applied normally based on its own configuration.

The restoring behavior depends on the restored Workspace's type:

A persistent Workspace is restored from the snapshot only on its first run. Afterwards, it is a regular, independent Workspace.
An ephemeral Workspace is restored from the snapshot on every run, which makes it a disposable, always-identical sandbox (e.g. for running untrusted code or for evaluating AI agents against the same baseline).

Forking via the SDKs

The SDKs make it easy to fork snapshots programmatically. Here is an example via the Go SDK that forks a baseline into several parallel Workspaces (read more about the APIs and SDKs here):

source, err := c.Workspaces().Get(ctx, "k3x9")
if err != nil {
	return err
}

if _, err := source.Snapshot(ctx, "ledger-baseline"); err != nil {
	return err
}

if _, err := c.Snapshots().WaitUntilReady(ctx, "ledger-baseline"); err != nil {
	return err
}

ws, err := c.Workspaces().Run(ctx, cordium.FromSnapshot("ledger-baseline"))
if err != nil {
	return err
}

You can read complete examples of forking Workspaces via snapshots here and here.

Deleting Snapshots

cordium delete snapshot ledger-baseline

Deleting the source Workspace does not delete its snapshots. A snapshot cannot be deleted while an ephemeral Workspace restores from it on every run, or while a persistent Workspace that is restored from it has not completed its first run yet.