Checkpoints and forks
Save a local sandbox's state as a named checkpoint and start new sandboxes from it.
Checkpoints of local sandboxes, the calls behind cua sb checkpoint, cua sb fork and cua sb checkpoints. A microVM checkpoint holds memory and disk, so a fork resumes running processes; a container checkpoint holds its filesystem. Forks of a QEMU checkpoint share its RAM copy-on-write, and a forkable sandbox checkpoints in milliseconds. A pinned checkpoint is kept until it is unpinned: delete refuses it and prune leaves it.
Checkpoint methods#
Methods of Sandboxes.
Sandboxes.checkpoint#
Saves sandbox name's state as checkpoint (memory and disk on a
microVM or a QEMU VM; a container's filesystem). It keeps running.
pin (default false) pins the new checkpoint (see
Sandboxes.pin_checkpoint). A QEMU checkpoint's forks share its
RAM copy-on-write (CheckpointSummary.shared_memory). name may
also be a Space another machine of yours provides (its name or id):
that machine takes the checkpoint and keeps it
(CheckpointSummary.host).
async def checkpoint(self, name: str, checkpoint: str, pin: bool = False) -> CheckpointSummary| Parameter | Type | Default |
|---|---|---|
name | String | required |
checkpoint | String | required |
pin | bool | false |
Returns CheckpointSummary · Async · Raises CuaError
Sandboxes.fork#
Starts name from a sandbox (running or stopped) or a checkpoint.
async def fork(self, source: str, name: str) -> Sandbox| Parameter | Type | Default |
|---|---|---|
source | String | required |
name | String | required |
Returns Sandbox · Async · Raises CuaError
Sandboxes.checkpoints#
Every checkpoint: this machine's (oldest first), then those your
machines that provide Spaces hold, each name once
(CheckpointSummary.host).
async def checkpoints(self) -> List[CheckpointSummary]Returns Vec<CheckpointSummary> · Async · Raises CuaError
Sandboxes.delete_checkpoint#
Deletes a checkpoint, here and on every machine of yours that holds a copy (forks made from it keep running). A pinned checkpoint is refused until it is unpinned.
async def delete_checkpoint(self, name: str) -> None| Parameter | Type | Default |
|---|---|---|
name | String | required |
Async · Raises CuaError
Sandboxes.pin_checkpoint#
Pins (pinned) or unpins a checkpoint. A pinned checkpoint is a
fork source to keep: delete_checkpoint refuses it and
prune_checkpoints leaves it until it is unpinned.
async def pin_checkpoint(self, name: str, pinned: bool) -> CheckpointSummary| Parameter | Type | Default |
|---|---|---|
name | String | required |
pinned | bool | required |
Returns CheckpointSummary · Async · Raises CuaError
Sandboxes.prune_checkpoints#
Deletes every checkpoint that is not pinned (forks made from them keep running); returns their names.
async def prune_checkpoints(self) -> List[str]Returns Vec<String> · Async · Raises CuaError
From a Space#
Methods of Space.
Space.checkpoint#
Saves this Space's state as checkpoint checkpoint (the sandbox
API's Sandboxes.checkpoint): it keeps running, and
Spaces.fork(checkpoint, name) (this machine) or Spaces.create
with image checkpoint:<name> (any of your machines) starts new
Spaces from it. pin (default false) keeps it until it is unpinned
(Sandboxes.pin_checkpoint). A Space another machine of yours
provides is checkpointed on that machine, which keeps the checkpoint
(CheckpointSummary.host).
async def checkpoint(self, checkpoint: str, pin: bool = False) -> CheckpointSummary| Parameter | Type | Default |
|---|---|---|
checkpoint | String | required |
pin | bool | false |
Returns CheckpointSummary · Async · Raises CuaError
Space.fork#
Starts Space name, a fork of this one (with its memory when it is
running), and returns it connected. To fork from a checkpoint, use
Spaces.fork(checkpoint, name). Local Spaces only.
async def fork(self, name: str) -> Space| Parameter | Type | Default |
|---|---|---|
name | String | required |
Returns Space · Async · Raises CuaError
Fork a Space#
Methods of Spaces.
Spaces.fork#
Starts Space name from source (a Space id such as
local:<name>, a sandbox name, a checkpoint name, or the tag of a
build (Spaces.build) or its checkpoint; a sandbox wins) and returns it
connected.
A running source is forked with its memory; a QEMU checkpoint's
forks share its RAM copy-on-write. A fork of a build has the build's
environment, working directory and user. Local sandboxes only.
async def fork(self, source: str, name: str) -> Space| Parameter | Type | Default |
|---|---|---|
source | String | required |
name | String | required |
Returns Space · Async · Raises CuaError
CheckpointSummary record#
A named checkpoint of a sandbox, and the machine that holds it.
Returned by Sandboxes.checkpoint, Sandboxes.checkpoints, Sandboxes.pin_checkpoint, Space.checkpoint.
| Field | Type | Default | Description |
|---|---|---|---|
name | String | The checkpoint's name. | |
source | String | The sandbox it was taken from. | |
runtime_type / runtimeType | String | The engine that holds it (firecracker, gvisor, qemu, ...). | |
created_at / createdAt | String | RFC 3339 creation time. | |
image | String | The source's image. | |
pinned | bool | Pinned: a fork source to keep (delete_checkpoint refuses it and prune_checkpoints leaves it until it is unpinned). | |
shared_memory / sharedMemory | bool | Its forks map its RAM copy-on-write and share the pages they do not write (a QEMU memory checkpoint). | |
release_with_forks / releaseWithForks | bool | Taken to fork a running sandbox many times (Sandboxes.fork_many of a sandbox): deleted with the last of its forks. | |
forks | u32 | How many of its forks still exist (for release_with_forks). | |
host | String | Where it is: empty for this machine, else the name of the machine of yours that holds it (a checkpoint of a Space that machine provides). Its forks start there (Spaces.create with image checkpoint:<name>, or fork_many), or on another machine after a verified copy. |