Snapshots
Cubicle snapshots are offline, disk-only copies of a stopped Box stored on its Node, used to restore the Box in place or create new Boxes, with rules for status, sizing, organization snapshots, hibernation and retention.
A snapshot is a named, point-in-time copy of a stopped Box's disk. You can restore the Box to it later, or create new Boxes from it. Taking, restoring and listing snapshots are covered step by step in Snapshot and restore a Box; this page explains what a snapshot is and the rules around it.
What a snapshot captures
A snapshot is a copy of the Box's root disk. It does not capture anything that lives only in memory.
| Captured | Not captured |
|---|---|
| Every file on the root disk: the operating system and installed software | Memory and running processes |
| The home directory of every user who has had access to the Box | Open network connections and SSH sessions |
| The guest accounts as they exist on the disk | The Box's name, size, private IP address or grants |
| A copy of the Linux kernel the Box boots, which Cubicle supplies | Saved hibernation memory (see below) |
- A snapshot is offline: the Box must be fully stopped while it is taken, so the disk is consistent.
- Size is not stored with the snapshot. A Box created from it starts from the source Box's current size (see Size rules).
Requirements
| Requirement | Rule |
|---|---|
| Box state | The Box must be stopped. Otherwise the request fails with 409 conflict "stop the box before taking a snapshot". |
| Fully stopped | The Node also checks that the Box is actually stopped when it runs the snapshot. Wait for state: "stopped" at the current generation. |
| Hibernated Boxes | A hibernated Box is not stopped. Stop it first, which discards its saved memory, then take the snapshot. |
| Permission | A grant on the Box, or the owner or admin role in its organization. API keys need the write scope. |
| Name | Matches ^[a-z0-9][a-z0-9._-]{0,62}$, for example before-upgrade. Names do not have to be unique, so refer to snapshots by id. |
If you request a snapshot before the Box has finished stopping, the snapshot operation can fail
with "box must be stopped". The SDK's box.stop() and the CLI's cubicle boxes stop --wait
wait for the stopped state for you. See Box lifecycle for states and
generations.
While a snapshot or restore is pending or running, start, stop, hibernate and delete requests
for that Box fail with 409 conflict "a snapshot or restore is in progress for this box".
Status
A snapshot request returns an operation of type snapshot. The snapshot
record appears in the Box's snapshot list as soon as the request is accepted, and its status
follows the operation.
status | Meaning |
|---|---|
pending | The operation is pending or running. The snapshot cannot be used yet. |
complete | The operation finished as done. You can restore from it or create Boxes from it. |
failed | The operation did not finish as done; its error says why. The snapshot can never be used. |
Any member of the Box's organization can list a Box's own snapshots, with
GET /v1/boxes/{box}/snapshots or the SDK's box.listSnapshots(). The list shows every snapshot
of that Box in every status, including pending and failed ones, newest first. Each entry has
id, name, status, operationId, createdAt and completedAt. The SDK's
box.snapshot(name) waits for the operation and returns the
Snapshot.
Where snapshots live
- A snapshot is stored on the Box's Node. It is not copied to other Nodes or to remote storage, so it is not a backup: it shares a Node with its Box and is deleted with it.
- A Box created from a snapshot is therefore placed on the snapshot's Node. If that Node is
unavailable or has no room for the new Box, creation fails with
503 capacity.
Restore in place or create a Box from a snapshot
You can use a complete snapshot in two ways.
| Restore in place | Create a Box from a snapshot | |
|---|---|---|
| Request | POST /v1/boxes/{box}/restore with snapshotId; box.restore(snapshotId) | POST /v1/orgs/{org}/boxes with snapshotId; cubicle.boxes.create({ snapshotId }) |
| Which snapshots | Only this Box's own snapshots | Any snapshot in the same organization whose source Box still exists |
| Permission | A grant on the Box, or owner or admin | A grant on the source Box, or owner or admin; the organization must allow Box creation |
| Box state | The Box must be stopped | The source Box can be in any state |
| Result | The same Box: its ID, name, private IP address, grants and SSH host key stay | A new Box with a new ID, hostname, private IP address and SSH host key |
| Disk | Replaced with the snapshot's disk. Current disk contents are lost. | A copy of the snapshot's disk, grown to the requested diskGiB |
| Kernel | The Box keeps booting its current kernel | Boots the kernel stored in the snapshot |
| Size | Unchanged | See Size rules |
| Access | Current grants and SSH keys are applied again before the Box accepts logins | Only you have a grant on the new Box |
| Returns | 202 with an operation of type restore | 202 with the new Box |
| Afterward | The Box stays stopped. Start it when the operation is done. | The Box starts unless you pass start: false |
What a restore changes
- The disk is replaced in one step, so an interrupted restore never leaves a half-written disk.
- Every guest account is applied again from current access. A restored disk cannot bring back access that was revoked after the snapshot: accounts without a current grant are locked when the Box starts.
What a Box created from a snapshot gets
The Node copies the snapshot's disk for the new Box right away, even when you create it with
start: false. Until that copy is done, deleting the source Box fails with 409 conflict
"box NAME is still being created from a snapshot of this box". After it, the new Box is
independent of the source Box and its snapshots.
The new Box's disk still holds every home directory from the source Box. Other users' accounts
stay locked, because only you hold a grant, but anyone with sudo in the new Box can read their
files. Remove data you do not want copied before you take the snapshot.
To prepare a Box once and create others from its snapshot, see Build a template Box.
Size rules for a Box created from a snapshot
| Field | Default | Rule |
|---|---|---|
baseImage | The source Box's base image | Cannot be set together with snapshotId: the request fails with 400 invalid_request. |
vcpus | The source Box's current vCPUs | Any value from 1 to 64. |
memoryMiB | The source Box's current memory | Any value from 256 to 262144 MiB. |
diskGiB | The source Box's current disk | At least the source Box's disk, up to 2048 GiB. A smaller value fails with 400 invalid_request "disk must be at least N GiB (the snapshot's size)". |
A larger disk is grown, together with its file system, before the new Box first boots. A disk
can never shrink. The new Box's name follows the usual
Box name rules.
Organization snapshots
To find snapshots you can create Boxes from, list the organization's snapshots with
GET /v1/orgs/{org}/snapshots or the SDK's cubicle.listSnapshots().
- The list holds only
completesnapshots whose source Box has not been deleted. - An owner or admin sees every such snapshot in the organization.
- A member sees snapshots of the Boxes they hold a grant on, because creating a Box from a snapshot copies that Box's data.
- Each entry has
id,name,createdAt, the sourcebox(id,name), itsnodeand the source Box'sspec, so you can choose a source and a size.
Snapshots and hibernation
Hibernation also saves state, but it is not a snapshot. Box lifecycle explains hibernation in full.
| Hibernation | Snapshot | |
|---|---|---|
| What it saves | Memory, running processes and device state, inside the Box's own disk image | The disk only |
| Box state | Taken from a running Box | Taken from a stopped Box |
| How many | At most one per Box | Any number per Box |
| Named, listed | No | Yes |
| Used by | The next start, which resumes the Box | A restore, or creating a new Box |
| Discarded by | Stopping the Box | Deleting the Box |
Retention and deletion
- Snapshots are kept until their Box is deleted. There is no API to delete a single snapshot.
- Deleting a Box deletes all of its snapshots. You can no longer restore from them or create Boxes from them.
- To keep a disk after deleting its Box, create a Box from one of its snapshots first. Deleting the source Box fails until the new Box's copy of the disk is done.
Related
Snapshot and restore a Box
Take a snapshot, restore it and create Boxes from it.
Build a template Box
Prepare a Box once and create new Boxes from its snapshot.
Box lifecycle
States, generations, stop and hibernation.
Commands and operations
How snapshot and restore operations are tracked.
Create a snapshot (API)
POST /v1/boxes/{box}/snapshots
Commands and operations
How exec runs a command in a Box (argv without a shell, no stdin or TTY, your own guest account, sudo and API keys), its results and limits, the grant and running Box it needs, generations, operation states, who can read an operation, idempotency keys and running several commands at once.
Networking
How Cubicle networking works, covering each Box's private IPv4 address, the WireGuard path from the cubicle CLI through Gateway, private DNS names under cubicle.internal, expiring access sessions, grants, SSH host-key pinning, outbound internet access and when to use SSH, the private network or the exec API.