running, boxd has two sleep states: standby keeps the memory in RAM, and hibernated writes it to disk. The deeper the sleep, the cheaper the machine is to keep around and the slower it is to wake. Both are fast enough for most use cases.
The states
A machine moves between these states on its own, based on network traffic. The idle timers count TCP/UDP traffic in both directions, so outbound traffic (polling an API, downloading packages, calling an LLM) keeps a machine awake just as an incoming request does, unless you turn on Ignore outbound traffic for it. Waking a sleeping machine takes inbound traffic: any inbound packet wakes a machine in standby, and a new connection through boxd (HTTPS, SSH,
boxd machine exec) wakes a hibernated one. You can also drive the transitions yourself: boxd machine pause and boxd machine resume for standby, boxd machine hibernate and boxd machine wake for hibernation.
A fourth state, stopped, is a machine you shut down with boxd machine stop. It keeps its disk and loses its memory and running processes, and boxd machine start boots it again.
The CLI prints standby. The API and the SDKs return suspended for the same state.
Driving the transitions by hand: pause, resume, then hibernate.
Auto-suspend
Off by default. When enabled, a machine goes to standby after N seconds without TCP/UDP traffic in either direction. Memory, running processes, and open sockets are all preserved. The first inbound packet (an SSH connection, an HTTP request, even a single TCP SYN) wakes it in sub-millisecond time. The caller can’t tell whether the machine was running or on standby, apart from the bot protection check on HTTPS requests.Auto-hibernate
On by default, set to 4 hours. After 4 hours without TCP/UDP traffic in either direction, boxd hibernates the machine: a memory image is written to disk and its memory is released. With the defaults a machine goes straight from running to hibernated, without passing through standby. From the outside the machine still exists with the same name, IP, and HTTPS domain. From the inside nothing appears to have happened. Waking from hibernation takes about 85ms and loads the memory image back into RAM. Tune or disable it per machine:boxd machine list shows hibernated machines with status: hibernated. A hibernated machine wakes on the next connection that comes through boxd: an HTTPS request to one of its domains, an SSH connection, boxd machine exec, or boxd machine wake. Traffic to a raw port forward doesn’t wake it yet; that’s on the roadmap. A machine on standby does wake on it.
Bot protection puts a quick browser check in front of HTTPS requests to
myapp.boxd.sh. With On, every request is checked, so crawlers can neither wake the machine nor keep it awake past its idle timers. With Sleep only, only a request that would wake it is checked. Webhooks and API clients that get checked receive a 503 instead of your app. Send that traffic to a subdomain proxy, or turn bot protection off for the machine.Ignore outbound traffic
Off by default. Withidle.ignore-outbound on, only connections opened to the machine count as activity: SSH, HTTPS requests, and connections from another machine. Connections the machine opens itself, such as polling an API, a background sync, or telemetry, no longer reset the idle timers, for auto-suspend and auto-hibernate alike. They don’t wake it from standby either, so a reply on one of its own connections leaves it asleep.
Turn it on for a background worker that only talks outbound and should sleep between jobs. Leave it off for anything that must stay up while it works over the network: with it on, a machine can go to standby or hibernate in the middle of a long download or API call.
A change applies to a running machine at once, without a restart. A fork keeps its source’s setting, and a machine created from a snapshot keeps the setting the snapshot was taken with, unless you set it when you create them.
boxd machine get myapp shows it as idle-ignore-outbound. In the console, it’s the Ignore outbound traffic switch on the machine’s Settings tab. Inside a machine, the in-machine CLI takes the same machine config set idle.ignore-outbound on command, and boxd info shows the machine’s value.
Org default
New machines start with your org’s default, if your org has one, and otherwise with the platform’s setting, which is off. A create that sets it itself still wins, so--idle-ignore-outbound=off keeps one machine out of an org default. Org admins set the default, and any member can read it.
Setting the default also changes the existing machines you can manage, your own machines and the org’s shared machines, and the snapshots you can manage, so machines created from them later get it too. Running machines pick it up at once. Other members’ private machines are left unchanged. To change only machines created from now on, use --new-only (in the SDKs, new_machines_only / newMachinesOnly).
changed 3 existing machines; 1 private machine owned by other members was left unchanged. Clearing the default never changes an existing machine.
In the console, it’s the Idle clock section on the Organization page. The menu sets the default for new machines, and Apply to existing machines then applies it to the existing machines you can manage. Platform setting in the menu means the org has no default of its own.
A fork or a machine created from a snapshot keeps its source’s setting, whatever the org default.
Pause, resume, hibernate, and wake by hand
You don’t have to wait for the idle timers. When you know a machine will be idle for a while, put it to sleep right away:pause requires the machine to be running. resume requires it to be in standby and fails on a hibernated machine, so use wake there. pause and resume accept --json:
suspend_us and resume_us report the actual time the pause and the resume took, in microseconds.
Pause compared to reboot
Use
pause when you want the machine to return to exactly where it was. Use reboot when you need a cold kernel or config restart. boxd machine stop also drops memory and running processes, and leaves the machine stopped until you start it.
How it works
boxd’s own VMM keeps a machine’s state as a memory image, in one of two storage tiers:- Run and capture. Your machine boots and your app initializes. When the machine goes to sleep, the VMM captures its full state (memory, CPU registers, device state) into a memory image.
- Standby in RAM. When no traffic flows for the auto-suspend timeout, or when you run
boxd machine pause, the memory image stays in RAM. Restoring it is sub-millisecond. - Hibernate to disk. After the auto-hibernate timeout, or when you run
boxd machine hibernate, the memory image is written to disk and the RAM is released. Restoring it takes about 85ms. - Wake on demand. When a request hits
<machine>.boxd.sh, or when you runboxd machine resumeorboxd machine wake, the VMM restores the memory image from whichever tier holds it, skipping boot, init, and app startup entirely.
What to use it for
- Pay for what you use. With auto-suspend on, a machine that serves occasional traffic goes to standby between requests.
- Keep idle machines cheap. A hibernated machine bills only for the disk it has written.
- Run many machines. Create hundreds of machines, let them hibernate when idle, and wake them on demand.
- Serve APIs without cold starts. A sleeping service answers its first request after a sub-millisecond resume from standby, or about 85ms from hibernation.
- Host agent workspaces. An agent’s machine hibernates after the conversation ends and wakes in about 85ms when the next one starts.