# Checkpoints and Forks

> Cordium documentation. Canonical page: <https://octelium.com/docs/cordium/latest/examples/workflows/snapshots>.

*WorkspaceSnapshots* capture the complete storage of a *Workspace*, including installed packages, build caches, databases running inside it and uncommitted changes (read more [here](https://octelium.com/docs/cordium/latest/workspaces/snapshots.md)). This example shows two workflows built on them: checkpointing a *Workspace* before a risky operation so that you can roll back, and turning a carefully prepared *Workspace* into an always-identical, disposable sandbox.

## Checkpointing Before Risky Changes

Suppose that you are about to upgrade the PostgreSQL major version used by your development *Workspace* `k3x9`, run a destructive data migration in it, or let an AI agent loose on it. First, stop the *Workspace* and take a clean snapshot of it:

```bash
cordium stop k3x9
cordium create snapshot before-pg18-upgrade --workspace k3x9
cordium get snapshot before-pg18-upgrade
```

Wait until the snapshot is `STATE_READY`, then start the *Workspace* again and proceed with the risky change:

```bash
cordium start k3x9
```

If anything goes wrong, you do not need to repair the *Workspace*: restore the snapshot into a brand new *Workspace* and continue from there, while keeping the broken one around for a post-mortem if you want:

```bash
cordium create ws --snapshot before-pg18-upgrade --start
```

The new *Workspace* belongs to the same *Space* and *Template* as `k3x9` and contains exactly what `k3x9` contained when you stopped it. Once you are confident in the result, delete what you no longer need:

```bash
cordium delete ws k3x9
cordium delete snapshot before-pg18-upgrade
```

> **Note:**
>
> You can snapshot a running *Workspace* as well, for example to checkpoint a long experiment without interrupting it. Such snapshots are crash-consistent, i.e. they do not include the data that running processes have not written to disk yet. For databases and other stateful processes, stop them or the whole *Workspace* first.

## Disposable Sandboxes from a Golden Snapshot

An ephemeral *Workspace* restored from a snapshot restores it on every run. This turns any prepared *Workspace* into a sandbox that always starts from the exact same state and discards everything when it stops, which is ideal for:

- Running untrusted or model-generated code against a realistic environment.
- Evaluating AI agents and models on the same tasks and the same starting point.
- Workshops, interviews and demos where every participant must get an identical environment.
- Reproducing a bug that requires a specific dataset, configuration and set of services.

First, prepare a *Workspace* with everything that the sandbox needs, for example a repository at a specific commit, its dependencies, a seeded database and the tools, then stop it and snapshot it:

```bash
cordium stop <WORKSPACE>
cordium create snapshot ledger-eval-v3 --workspace <WORKSPACE>
```

Then, create one ephemeral *Workspace* per session from the snapshot. Here is an example via the Python SDK that runs a candidate solution in a fresh copy of the golden environment and resets it between two runs simply by restarting it:

```python
from cordium import Cordium

with Cordium() as client:
    client.snapshots.wait_until_ready("ledger-eval-v3")
    sandbox = client.workspaces.create(snapshot="ledger-eval-v3", ephemeral=True)
    try:
        for attempt in ["solution-a.patch", "solution-b.patch"]:
            sandbox.start()
            sandbox.wait_until_running(timeout=600)
            with open(attempt, "rb") as f:
                sandbox.files.write_bytes("/tmp/solution.patch", f.read())
            result = sandbox.exec(
                "git apply /tmp/solution.patch && go test ./internal/ledger/...",
                cwd="/workspace/repo",
                timeout=1800,
            )
            print(f"{attempt}: exit code {result.exit_code}")
            sandbox.stop()
            sandbox.wait_until_stopped(timeout=600)
    finally:
        sandbox.delete()
```

Since the *Workspace* is ephemeral, stopping it discards its storage, and the next start restores the snapshot again. A snapshot cannot be deleted while an ephemeral *Workspace* restores from it.

## Forking into Parallel Workspaces

A snapshot can also be restored into many *Workspaces* at once, for example to shard a long test suite or to give the same task to several AI agents. Read the complete examples [here](https://octelium.com/docs/cordium/latest/use/api.md#forking-workspaces-from-a-snapshot) and [here](https://octelium.com/docs/cordium/latest/examples/ai/parallel-agents.md).