Saving & restoring state

The DataFrames, fitted models, and other variables in a notebook live inside a kernel in the project's sandbox. Clusy checkpoints that namespace at specific durability boundaries so it can be restored after the live machine is gone.

The two user-facing durability boundaries

Saving every live kernel and the workspace takes real time, so it happens at these boundaries rather than after every cell.

In particular, branching does not create a durable checkpoint. A fork copies the parent namespace directly to another kernel in the same running sandbox. That makes it fast, but the new branch becomes durable only when the project next reaches a boundary.

New share links are content snapshots and do not include kernel state. See Sharing.

A leave boundary saves a durable bundle before the runtime pauses or is released. CPU usually resumes with memory intact; after a release or unavailable machine, a fresh sandbox restores the saved state without rerunning the notebook.

Leaving and coming back

You do not press Save. A project is still in use while a browser is connected or an agent turn is running. Once both reach zero, Clusy waits 60 seconds and then:

1. stops accepting new cells,
2. gives running cells up to 30 seconds to finish, then interrupts any that remain,
3. saves each live kernel, workspace files, and the package environment,
4. checks whether anyone returned,
5. and pauses the sandbox only if the project is still empty.

Returning during the sequence wins: the leave is abandoned and the sandbox stays available.

On the normal CPU path, reopening resumes the paused machine and its memory is already present. If that machine is unavailable—or after a GPU sandbox was released—a fresh sandbox restores from the durable bundle instead.

What survives

• Notebook cells and outputs are stored independently of kernel memory.
• Kernel variables are serialized at a boundary.
• Workspace files are captured with the boundary bundle and restored into a rebuilt sandbox.
• Installed packages are recorded and reinstalled best-effort. Keeping important installs in a cell remains the most reproducible approach.

Each successful save replaces the previous restore point. State persistence is a resume mechanism, not version history; use GitHub for history.

What a checkpoint cannot carry

Live and unpicklable objects

Open file handles, active database connections, CUDA and other device contexts, and some library internals cannot be serialized. The rest of the namespace still saves, and Clusy names excluded variables when possible. Re-create these resources in a small, rerunnable cell.

A namespace over 4 GiB

Each branch checkpoint is capped at 4 GiB. Crossing the cap does not turn a successful cell into a failed cell; it means the new namespace cannot become the saved checkpoint. Clusy shows a durability notice, and a later restore uses the last valid state.

Write large objects to the workspace instead—for example, df.to_parquet(...) or torch.save(...)—and rebuild the in-memory form after a restart.

Changing the sandbox

Changing hardware or RAM replaces the machine. When there is state to lose, the picker asks you to choose:

• Transfer state (recommended): checkpoint variables and restore them on the new machine. Unpicklable objects stay behind, and the transfer can take a few minutes.
• Start clean: move without the namespace. Cells and visible outputs remain, while variables start empty and need rebuilding.

Notebooks, workspace files, packages, and the environment survive either choice. A transfer that cannot capture the current namespace is refused with an explanation; you can save large objects to files or choose Start clean.

The sandbox type is different: it locks after the first successful cell and cannot be changed. See Runtimes & sandboxes.

Saved-state storage

Settings → Storage reports saved kernel checkpoint bytes across projects you own against this plan allocation:

Notebooks, uploads, datasets, workspace files, outputs, and packages do not count toward this volume.

If a new checkpoint slot is refused, Clusy shows a Storage is full dialog. An existing branch can still replace its current checkpoint so running work is not stranded. There is no storage pay-as-you-go.

Settings → Storage shows usage by project. Clearing a project's saved kernel state discards its primary kernel variables, like restarting that kernel, without deleting notebooks, files, packages, outputs, or the environment. Delete an experiment branch to reclaim that branch's checkpoint.

Paused sandbox availability

Paused sandboxes do not have a guaranteed plan-based retention period. A paused machine can become unavailable for operational reasons. Releasing it does not delete notebook content or the durable state bundle; reopening cold-starts a sandbox and restores from the saved copy instead of resuming the old machine.

The crash edge

Because checkpointing is boundary-based, an abrupt sandbox loss can lose variables and workspace files created since the last boundary. Files already flushed by the previous completed boundary and persisted notebook content remain.

A branch that has no usable checkpoint returns view-only instead of pretending it can run. You can inspect, export, or delete it, then continue from a branch that still has state or rerun the cells needed to rebuild it.

For expensive work, write intermediate results to files so they can be rebuilt without the live namespace and captured at the next completed boundary. A newly written workspace file is still at risk before that boundary; download or publish a critical artifact if you need an immediate off-sandbox copy.