Stop, hibernate and wake a Box

A running Box can be stopped or hibernated. Stopping shuts the guest down and keeps its disk. Hibernating also saves the Box's memory to its disk, so its processes carry on where they were when it wakes. A running Box also hibernates by itself 60 minutes after it starts. Box lifecycle describes every state.

Before you beginCopy Anchor Link

• Set up the SDK or the CLI as in the Quickstart. The examples use a running Box acme/job-1 (cubicle boxes create --org acme job-1 --wait). TypeScript snippets use const box = cubicle.boxes.ref("acme/job-1"), and curl snippets read a write key from CB_SDK_API_KEY and use jq.
• You need a grant on the Box, or the owner or admin role in its organization. An API key needs write scope.

Choose stop or hibernateCopy Anchor Link

Hibernate when you want to pick up running work later, such as a dev server or a background job. Stop when you want a clean boot, or before you take a snapshot.

A free Omarchy Box (pooled: true) is the exception: while it is stopped or hibernated it gives up its vCPUs and memory, and it is deleted at expiresAt unless you start it.

Hibernate a BoxCopy Anchor Link

The Box's desired state must be running. A Box that is already hibernated is left as it is, and the request still succeeds.

const info = await box.hibernate() // waits until the Box is hibernated, up to 5 min
console.log(info.state) // => "hibernated"

The CLI cannot hibernate a Box. Use the SDK, the API or Hibernate in the Dashboard.

Stop a BoxCopy Anchor Link

const info = await box.stop() // waits until the Box is stopped, up to 5 min
console.log(info.state) // => "stopped"

Stopping a hibernated Box discards its saved memory and keeps its disk. The Dashboard calls this Discard saved memory.

Automatic hibernationCopy Anchor Link

A running Box hibernates 60 minutes after its current start first reports running, whatever it is doing: SSH sessions, execs and background jobs do not extend the hour, and you cannot turn automatic hibernation off or change the hour. hibernateAt in the Box's record says when it will happen (details).

const info = await box.info()
console.log(info.hibernateAt) // => "2026-11-05T11:02:17.000Z"

Every start begins a fresh hour. To get one for a running Box, start it again: it does not reboot, but SSH and private-network traffic pause until its Node applies the new generation. After automatic hibernation, exec requests fail with 409 conflict "box is not running" until you wake the Box.

Wake a BoxCopy Anchor Link

Starting a Box resumes it from saved memory if it is hibernated, and cold-boots it if it is stopped.

await box.start() // waits until SSH and exec can be used, up to 5 min

In the Dashboard, a hibernated Box shows "Hibernated · Start resumes saved memory".

Check what survivedCopy Anchor Link

The kernel's boot ID changes on every boot, so it shows whether the Box resumed or booted again:

const bootId = ["cat", "/proc/sys/kernel/random/boot_id"]

const before = await box.exec(bootId)
await box.hibernate()
await box.start()
const afterResume = await box.exec(bootId)
console.log(afterResume.stdout === before.stdout) // => true: memory and processes survived

await box.stop()
await box.start()
const afterBoot = await box.exec(bootId)
console.log(afterBoot.stdout === before.stdout) // => false: a stop means a cold boot

TroubleshootingCopy Anchor Link

• SDK CubicleBoxError with code hibernation_failed, "box job-1 could not hibernate: …; the Controller retries at …": saving memory failed. The Box keeps running, its desired state returns to running, observed.error holds the error and hibernationRetryAt says when Cubicle tries again. It retries after 30 s, then doubles the delay up to 5 min, so you need not do anything. If you need the Box off now, stop it: cubicle boxes stop acme/job-1 --wait. Stopping it, or starting it for a fresh hour, ends the retries.

  Copy Text

  import { CubicleBoxError } from "@cubicle/sdk"
  
  try {
    await box.hibernate()
  } catch (error) {
    if (error instanceof CubicleBoxError && error.code === "hibernation_failed") {
      console.log(error.box.observed?.error, error.box.hibernationRetryAt)
    }
  }

• restartRequired: true, or 409 conflict "the box requires an explicit Start after a host reboot" on a hibernate: the Box's host rebooted and its memory is gone. Start the Box; see restartRequired: true.

• A hibernated Box stays hibernated after a host reboot: a host reboot never resumes a hibernated Box. Start it.

• state: failed after a start, with observed.error "Saved VM configuration is incompatible; Stop then Start for a cold boot": the host's QEMU version or CPU, or the Box's kernel or size, changed since it hibernated, so the saved memory cannot be loaded. Stop the Box, which discards the saved memory, then start it. In the SDK, start rejects with CubicleBoxError code box_failed. Any other failed resume whose error tells you to stop has the same fix.

• 409 conflict "only a running box can hibernate": the Box's desired state is stopped. Start it first if you want to hibernate it.

• SDK CubicleBoxError with code box_superseded, "box job-1 is now requested hibernated, not running": something else changed the Box's desired state while you waited, such as another client or automatic hibernation. Read the Box and decide again.

RelatedCopy Anchor Link

• Box lifecycle: every state, generations and readiness.
• Run commands: exec with wake: true and work longer than one exec's 10-minute limit.
• Snapshot and restore a Box: save a stopped Box's disk.
• Waiting and Errors and retries: the SDK's waits and error classes.
• cubicle boxes start and cubicle boxes stop: the CLI reference.
• Hibernate a Box, Start a Box and Stop a Box: the API reference.