> ## 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
> 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 that callers can't tell.
Built on [Ignition](https://github.com/lttle-cloud/ignition), the open-source microVM orchestrator by Azin that powers sub-10ms cold starts.
## 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
```
**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.
A hibernated VM costs effectively zero to keep around. This is what makes idle goldens and rarely-hit preview environments practical: the workload sits in a `hibernated` state for hours or days at near-zero cost, then resumes in under 100ms on the next request.
`boxd machine list` shows hibernated VMs with `status: hibernated`. They wake automatically on the first inbound packet.
## Manual pause / resume
You don't have to wait for the idle timers. 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. No boot, no init, no app startup.
The transitions are transparent to your app. From the inside, the VM's clock jumps forward and the next packet arrives. No reconnects, no re-reads of state.
## What this enables
* **Pay for what you use.** Machines that serve occasional traffic suspend between requests.
* **Idle goldens stay near-free.** Hibernation means an unused fork-source VM costs effectively nothing to leave running for weeks.
* **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 VM 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)
## Reference
`pause`, `resume`, `auto-suspend` from your local terminal.
Quotas, CPU, memory, and disk.