Skip to main content

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.

Machines can be frozen in place — memory, running processes, open sockets, all preserved — and woken up in under a millisecond when traffic arrives or you explicitly resume them. Pay nothing for idle compute; pick up exactly where you left off when the next request hits. Built on Ignition, the open-source microVM orchestrator by Azin that powers sub-10ms cold starts.

​
The two modes

Auto-suspendManual pause
TriggerNo inbound TCP/UDP traffic for N secondsExplicit boxd pause command
Wake triggerFirst inbound TCP/UDP packetExplicit boxd resume command
Statusstandbystandby
MemoryPreservedPreserved
Resume timeSub-millisecondSub-millisecond
Both use the same underlying snapshot mechanism. The only difference is who triggers the freeze and the wake.

​
Auto-suspend (default)

Every machine auto-suspends after 30 seconds of no inbound TCP/UDP traffic. When a packet arrives (SSH connection, HTTP request, even a single TCP SYN), the machine wakes in sub-ms and handles it. The caller can’t tell whether the machine was running or suspended. 
boxd info myvm                         # shows "auto-suspend: 30s" or "off"
boxd auto-suspend myvm 0               # disable auto-suspend on this VM
boxd auto-suspend myvm 300             # change to 5 minutes
boxd new --auto-suspend-timeout=60     # set at creation
boxd fork src --auto-suspend-timeout=0 # disable on the fork
Auto-suspend watches for network activity, not CPU activity. A long training run, batch job, file encode, or cron-driven task that doesn’t touch the network looks idle to the host and will get suspended mid-work. Clocks also freeze while suspended — cron and systemd timers won’t fire until the next inbound packet arrives.Disable auto-suspend (boxd auto-suspend NAME 0) on any VM that needs to keep running in the background without continuous network traffic.

​
Manual pause / resume

Pause a machine immediately without waiting for auto-suspend to fire. Useful when you know a VM will be idle for a while and want to stop paying for it right now. 
boxd pause myvm                        # freeze now
boxd resume myvm                       # wake now
Pause requires the VM to be running. Resume requires it to be in standby. Both commands accept --json: 
boxd pause myvm --json
# {"name":"myvm","status":"standby","suspend_us":23500}

boxd 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 pauseboxd reboot
Kernel / VMM processKept alive, frozenKilled, respawned
MemoryPreservedLost
Running processesContinue on resumeMust restart
Open network connectionsPreservedDropped
Wake timeSub-millisecond~2 seconds
DB statusstandbybooting → 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:
  1. Run and snapshot. Your machine boots, your app initializes, and Ignition captures the full VM state — memory, CPU registers, device state — into a snapshot.
  2. Suspend when idle (or on command). The host watches the tap interface for inbound IPv4 TCP/UDP packets. When none arrive for auto_suspend_timeout seconds, or when you run boxd pause, the machine suspends. The snapshot is retained in memory or on disk.
  3. Resume on demand. When a request arrives at name.boxd.sh, or when you run boxd resume, the machine restores from the snapshot — no boot, no init, no application startup.

​
What this enables

  • Pay for what you use. Machines that serve occasional traffic suspend between requests.
  • Massive parallelism. Spin up hundreds of machines, let them suspend when idle, wake on demand.
  • Instant APIs. Deploy a service that cold-starts faster than a DNS lookup.
  • Agent workspaces. An agent’s VM auto-suspends when the conversation ends and resumes instantly when the next one starts.

​
Learn more

Ignition is open source. Read the code and architecture:

​
Reference

External CLI

pause, resume, auto-suspend from your local terminal.

Resources and limits

Quotas, CPU, memory, and disk.