Box lifecycle

The SDK's lifecycle methods and the CLI's --wait flag wait for each change for you; see Waiting. Read on if you poll the HTTP API yourself, or want to know what each state and field means.

In words: create takes a new Box through pending, provisioning and starting to running. Stop takes a running Box to stopped, and start brings it back. Hibernate, or automatic hibernation 60 minutes after a start, takes a running Box to hibernated, and start resumes it. Stop takes a hibernated Box to stopped and discards its saved memory. Delete works from any state: the Box shows deleting and is then removed. failed and unknown are not drawn; see What each state means.

What each state meansCopy Anchor Link

• state is the Node's latest report, so right after a request it can still show the state from before it. Under the hood explains how to tell when a request has taken effect.
• You can send start, stop or delete in any state, and hibernate whenever the desired state is running, apart from the conflicts listed under How requests move a Box. The Node finishes its current step, then applies the latest request.
• The BoxState type also lists absent, which the API does not return, and deleted, which appears only when a create repeated with its Idempotency-Key returns a Box that its Node has already removed, together with deletion: "complete". See Idempotency keys.

How requests move a BoxCopy Anchor Link

Lifecycle requests need a grant on the Box, or the owner or admin role in its organization. They return 409 conflict in these cases:

• Hibernate, unless the desired state is running: only a running box can hibernate. A Box that is already hibernating or hibernated accepts it without change.
• Hibernate, while the Box waits for a start after a host restart: the box requires an explicit Start after a host reboot.
• Start, stop, hibernate and delete, while a snapshot or restore of the Box is pending or running: a snapshot or restore is in progress for this box. A running exec does not block them.
• Delete, while another Box is still being created from one of this Box's snapshots.

Read Generations before you start a Box that is already running.

Boxes hibernate 60 minutes after each startCopy Anchor Link

• When a Box first reports running after a start, hibernateAt is set to 60 minutes later. At that time Cubicle hibernates it, as if you had sent hibernate.
• SSH sessions, execs, console use and network traffic do not extend the deadline.
• Every start sets a fresh 60 minutes, including a start on a Box that is already running.
• hibernateAt is null while the desired state is not running, while the Box waits for a start after a host restart, and before the first running report.
• Hibernation interrupts running execs. They end unknown and are never run again.

Hibernation pauses the Box's vCPUs and saves its memory and device state on its disk. Start resumes the Box from that saved state, with its processes where they were. SSH and private-network connections to the Box end, and other open connections may not survive.

When saving fails, the guest keeps running. The desired state returns to running, the error is in observed.error, and hibernationRetryAt says when Cubicle tries again: after 30 s, then twice as long each time, up to 5 minutes. A hibernate you request yourself retries the same way.

When the Node's QEMU version, CPU, kernel or the Box's configuration changed after the save, resume fails: the Box goes to failed with Saved VM configuration is incompatible; Stop then Start for a cold boot. Stop it to discard the saved memory, then start it.

Stop, hibernate and wake a Box has the steps in the SDK, the API and the Dashboard; the CLI has no hibernate command.

What stop, hibernate and delete keepCopy Anchor Link

• Stopping a hibernated Box discards its saved memory and keeps the disk. The Dashboard calls this Discard saved memory.
• Snapshot and restore need a stopped Box. Stop a hibernated Box first. See Snapshots.
• A free Omarchy Box is the exception: it gives back its vCPUs and memory while stopped or hibernated, and is deleted at expiresAt unless you start it.

A host restart needs an explicit startCopy Anchor Link

When a Node's host restarts, Cubicle does not start its Boxes again by itself. Every Box that should have been running shows:

• restartRequired: true
• state: "stopped", reported at the generation the Node last applied, while desired.state is still running
• ssh.reason and console.reason restart_required
• hibernateAt: null; hibernate returns 409 conflict

Start the Box to boot it again, or stop it to leave it stopped. Either clears restartRequired. Its memory was lost with the host, so the start is a cold boot.

Hibernated Boxes stay hibernated through a host restart. Start resumes them as usual.

Failures are reported, not retriedCopy Anchor Link

A Box whose start or other Node action fails shows state: "failed", with the reason in observed.error. box failed: <error> lists each error with its cause and fix.

• A Box does not restart in place. A reboot or shutdown from inside the Box leaves it failed; start it again.
• Cubicle does not retry a failed start. Start the Box to try again, or stop or delete it.
• A failed hibernation is not failed: the Box keeps running. See Boxes hibernate 60 minutes after each start.
• A failed report keeps observed.generation at the last generation the Node applied, so right after a new start it can be left over from the earlier one. Following a request says how to tell whether it belongs to your request.

Deleting a BoxCopy Anchor Link

DELETE /v1/boxes/{box}, box.delete() and cubicle boxes delete acme/job-1 delete a Box. The request returns 202 with desired.state: "deleted" and deletion: "pending". Deletion is permanent.

When the deletion is accepted:

• running execs end unknown, and operations that have not started fail with box deleted
• the Node stops the VM without a guest shutdown, then removes its disk and every snapshot of it
• GET /v1/boxes/{box} and every other route for the Box return 404
• the name is free for a new Box

Box listings (GET /v1/orgs/{org}/boxes, GET /v1/boxes and cubicle.boxes.list()) keep showing the Box with deletion: "pending", usually in state deleting, until its Node confirms the removal. The Box then disappears from the listings, and its vCPUs, memory, disk and private IP address are released. Deletion shows how to wait for that, and Waiting and cubicle boxes delete say what the SDK and the CLI wait for.

Under the hood: desired and observed stateCopy Anchor Link

You change a Box by requesting a new desired state. Every lifecycle request returns 202 with the Box as it is at that moment, or 200 for a create repeated with the same Idempotency-Key. The Box's Node carries out the change afterwards and reports back. A Box record carries both sides:

• desired is what was last requested: { state, generation }.
• observed is the Node's latest report: { state, generation, observedAt, ageSeconds, fresh, error }. It is null until the Node first reports on the Box.
• state is derived from observed. It is unknown when the report is not fresh.

This Box has accepted a stop, but its Node last reported it running:

{
  "state": "running",
  "desired": { "state": "stopped", "generation": 5 },
  "observed": {
    "state": "running",
    "generation": 4,
    "observedAt": "2026-11-05T10:00:02.000Z",
    "ageSeconds": 1,
    "fresh": true,
    "error": null
  },
  "ssh": { "ready": false, "reason": "not_requested" }
}

Once the Node has stopped the Box, it reports stopped at generation 5. Following a request gives the full polling loop.

Generations show when a request has taken effectCopy Anchor Link

Each Box has two counters: desired.generation and connectionGeneration.

desired.generation advances with each of these:

• every accepted start and stop, even when the Box is already in that state
• hibernate, unless the Box is already hibernating or hibernated
• automatic hibernation
• a failed hibernation, which returns the desired state to running
• delete

observed.generation is the generation the Node last applied. A request has taken effect when the Box reports its target state and observed.generation equals desired.generation. For a start, use ssh.ready, which is true only at the current generation.

connectionGeneration advances whenever desired.generation does, except after a failed hibernation. It also advances with every restore and when the Node's host restarts. Guest accounts, private-network access and the published SSH host key from an earlier value no longer apply, so SSH and private-network traffic reaches the Box only once it runs at the new value. The host key itself does not change. Reconnect once ssh.ready is true again.

A start on a Box that is already running does not reboot it, but it still does all of this:

• advances both counters
• makes ssh.ready false, with the reason generation_pending, until the Node has applied the new generation. The Node does that once execs already running on the Box have finished.
• keeps SSH and private-network traffic from reaching the Box until then; open connections may not survive the gap
• applies the Box's accounts again
• restarts the 60-minute hibernation clock

So check desired.state before you send a start. The SDK's box.exec(argv, { wake: true }) starts the Box only when it is not already meant to be running, or when it needs a start after a host restart.

An exec is also bound to the generation at which it was accepted. See Commands and operations.

When a Box is readyCopy Anchor Link

ssh.ready is true when the Box is running at its current generation on a healthy Node and its SSH host key is published. Exec, new SSH connections and new private-network connections work then. When it is false, ssh.reason names the first check that failed, in the order of the first ten rows of the table below.

ssh.ready describes the Box, not you: it does not check your grant or your SSH keys. GET /v1/boxes/{box}/ssh (reference) reports whether you can connect. It runs the Box's checks first and then yours, so it can also return the last five reasons in the table. See SSH into a Box.

Where you see the reason:

• cubicle boxes list shows the Box's reason as ssh=<reason>.
• cubicle ssh-config also checks your own access, and prints (not ready: <reason>).
• The Dashboard words each reason as quoted in the table: the Box's under SSH readiness on the State tab of the Box's details, and yours on its Access tab.

console.ready reports whether the desktop console can be used. It does not depend on SSH: it needs the VM's display, reported by the Node for the Box's current connection generation within the last 15 s. Check console readiness lists each console.reason and what to do.

RelatedCopy Anchor Link