> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Suspend, resume, and hibernate

> Freeze a machine and wake it in milliseconds.

Machines can be frozen in place and woken on demand. boxd has three lifecycle states for a VM, with two levels of suspend depending on how long it's been idle. The deeper the sleep, the cheaper to keep around, the slower to wake. Both are fast enough for most usecases.

Built on [Ignition](https://github.com/lttle-cloud/ignition), our open-source microVM orchestrator, which layed the foundation of what boxd now is.

## The three states

| State          | Memory          | Wake time       | Cost             |
| -------------- | --------------- | --------------- | ---------------- |
| **running**    | Live in RAM     | already running | full             |
| **standby**    | Frozen in RAM   | sub-millisecond | near zero        |
| **hibernated** | Written to disk | \~85ms          | effectively free |

A VM moves through these states automatically based on inbound network activity. You can also drive transitions yourself with `boxd machine pause` / `boxd machine resume`.

## Auto-suspend (running → standby)

**Off by default.** When enabled, a machine suspends after N seconds of no inbound TCP/UDP traffic. The machine freezes in place. Memory, running processes, and open sockets are all preserved. The first inbound packet (SSH connection, HTTP request, even a single TCP SYN) wakes it in **sub-millisecond** time. The caller can't tell whether the machine was running or suspended.

```bash theme={"theme":"github-dark"}
boxd machine get myvm                                 # shows "auto-suspend: 300s" or "off"
boxd machine config set myvm auto-suspend.timeout 300 # suspend after 5 minutes idle
boxd machine config set myvm auto-suspend.timeout 0   # turn it back off
boxd machine new --auto-suspend-timeout=60            # set at creation
boxd machine fork src --auto-suspend-timeout=0        # disable on the fork
```

## Auto-hibernate (→ hibernated)

**On by default, set to 4 hours.** After 4 hours of no inbound TCP/UDP traffic, boxd hibernates the machine: a snapshot is written to disk and its memory is released. From the outside the machine still exists with the same name, IP, and HTTPS domain. From the inside the VM has no idea anything happened. Wake from hibernation takes **\~85ms** and replays the snapshot back into RAM.

Tune or disable it per VM:

```bash theme={"theme":"github-dark"}
boxd machine config set myvm auto-hibernate.timeout 86400 # hibernate after 24h idle instead
boxd machine config set myvm auto-hibernate.timeout 0     # never hibernate this VM
```

<Warning>
  **The idle timers watch network activity, not CPU.** A long training run, batch job, file encode, or cron-driven task that doesn't touch the network looks idle — after 4 hours it gets hibernated mid-work (or suspended sooner, if you enabled auto-suspend). Clocks also freeze while suspended or hibernated. Cron and systemd timers won't fire until the next inbound packet arrives.

  Disable auto-hibernate (`boxd machine config set NAME auto-hibernate.timeout 0`) on any VM that needs to keep running in the background without continuous network traffic.
</Warning>

`boxd machine list` shows hibernated VMs with `status: hibernated`. They wake automatically on the first inbound packet.

## Manual pause and resume

If you don't have to wait for the idle timers, you can pause a machine immediately when you know it'll be idle for a while:

```bash theme={"theme":"github-dark"}
boxd machine pause myvm  # freeze now
boxd machine resume myvm # wake now
```

Pause requires the VM to be `running`. Resume requires it to be in `standby`. Both accept `--json`:

```bash theme={"theme":"github-dark"}
boxd machine pause myvm --json
# {"name":"myvm","status":"standby","suspend_us":23500}

boxd machine resume myvm --json
# {"name":"myvm","status":"running","resume_us":840}
```

`suspend_us` and `resume_us` report the actual snapshot/restore time in microseconds.

## pause vs reboot

|                          | `boxd machine pause`  | `boxd machine reboot`             |
| ------------------------ | --------------------- | --------------------------------- |
| Machine process          | Kept alive, frozen    | Killed, respawned                 |
| Memory                   | Preserved             | Lost                              |
| Running processes        | Continue on resume    | Must restart                      |
| Open network connections | Preserved             | Dropped                           |
| Wake time                | Sub-millisecond       | \~2 seconds                       |
| State                    | `running` → `standby` | `running` → `booting` → `running` |

Use `pause` when you want the VM to return to exactly where it was. Use `reboot` when you need a cold kernel/config restart.

## How it works

Ignition uses a snapshot-based approach with two storage tiers:

1. **Run and snapshot.** Your machine boots, your app initializes. Ignition captures the full VM state (memory, CPU registers, device state) into a snapshot.
2. **Suspend in RAM (standby).** When no inbound packets arrive for `auto_suspend_timeout` seconds, or when you run `boxd machine pause`, the snapshot is retained in memory. Sub-millisecond to restore.
3. **Hibernate to disk.** After an extended idle window, the snapshot moves from RAM to disk and memory is released. \~85ms to restore from disk on the next inbound packet.
4. **Wake on demand.** When a request hits `name.boxd.sh`, or when you run `boxd machine resume`, Ignition restores from whichever tier the snapshot lives in, skipping boot, init, and app startup entirely.

The transitions are transparent to your app. From the inside, the VM's clock jumps forward and the next packet arrives. Connections stay open and in-memory state is still there.

## What this enables

* **Pay for what you use.** Machines that serve occasional traffic suspend between requests.
* **Idle machines stay near-free.** Hibernation means an unused machine costs effectively nothing to keep around.
* **Massive parallelism.** Spin up hundreds of machines, let them suspend and hibernate when idle, wake on demand.
* **Instant APIs.** Deploy a service that cold-starts faster than a DNS lookup.
* **Agent workspaces.** An agent's machine hibernates when the conversation ends and resumes instantly when the next one starts.

## Learn more

Ignition is open source. Read the code and architecture:

* [github.com/lttle-cloud/ignition](https://github.com/lttle-cloud/ignition)
* [DeepWiki: Ignition](https://deepwiki.com/lttle-cloud/ignition)