# Snapshots

> Cordium documentation. Canonical page: <https://octelium.com/docs/cordium/latest/workspaces/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](https://octelium.com/docs/cordium/latest/management/storage.md)).

## Taking Snapshots

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

```bash
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:

```bash
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](https://octelium.com/docs/cordium/latest/workspaces/resources.md#quotas)).

## Restoring Snapshots

Restore a snapshot into a new *Workspace* as follows:

```bash
# 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](https://octelium.com/docs/cordium/latest/use/api.md)):

```go
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](https://octelium.com/docs/cordium/latest/examples/workflows/snapshots.md) and [here](https://octelium.com/docs/cordium/latest/examples/ai/parallel-agents.md).

## Deleting Snapshots

```bash
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.