Checkpoints and Forks

WorkspaceSnapshots capture the complete storage of a Workspace, including installed packages, build caches, databases running inside it and uncommitted changes (read more here). 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:

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:

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:

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:

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:

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:

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 and here.