Sleep, wake, and recover a devbox

Devboxes and Template boxes sleep when you aren't using them. Sleeping keeps the machine's files and memory, like closing a laptop's lid, so you can return to the same machine later. Nothing runs while it sleeps: agent work and your app pause until the machine wakes.

Automatic sleep and wake

A Template box or devbox normally sleeps after about five minutes without activity. An agent still working, you interacting with the machine, or visitors actively using a public link you've shared can keep it awake longer; the idle timeout itself is not configurable. Sleeping machines use no active box-hours and release awake capacity, while awake Template boxes and devboxes count against your plan's box-hours.

Automatic waking is on by default, so a sleeping machine will normally wake when you return to its thread or Template box page. To change this, use Wake sleeping machines automatically in the titlebar's machine status menu. The preference is saved for your account and covers your project devboxes and ordinary Template boxes. The same setting is available under Project settings → Devbox lifecycle → New devbox defaults.

With automatic waking off, you can select a sleeping machine and read its conversation while it stays asleep. Choose Wake in the titlebar to start using the machine again, or use the wake control in Terminal, Files, Git/Review, or Ports. Sending a message to the agent will also wake its machine, even with automatic waking off. Archived conversations remain readable without a running machine.

On desktop, a message sent to a sleeping thread will wait in the queue while the machine wakes. Keep the app open until the message and its attachments reach boxes.dev; delivery can then continue after you close the app. See waiting for startup for cancellation and attachment recovery.

Sleep and wake

Sleep a devbox yourself when you're stepping away but plan to return, or to free awake capacity for another devbox. If you're finished with the machine entirely, destroy it instead — sleeping keeps it.

1. Select a thread on the devbox you want to sleep.
2. Open the machine status menu in the desktop titlebar and choose Sleep devbox. An agent still working there will pause with the machine.
3. To return, select the devbox and choose Wake in the titlebar, or Wake devbox in Terminal, Files, Git/Review, or Ports.

For a Template box, open its page from the sidebar first and use Sleep Template box or its wake control. Check the selected machine before using either action.

Waking can take several seconds or a few minutes, and programs on the machine may need to reconnect their network connections afterward. If an agent was working when the machine slept, check its thread after waking. If the work was interrupted, send a follow-up to continue.

If a wake attempt fails, the machine returns to sleeping rather than retrying continuously. In the warning banner, choose Try again to retry a normal wake, or Reboot… to start the machine without restoring its saved memory. The titlebar's Wake control also retries a normal wake. With automatic waking on, returning to the machine after 15 minutes can make one new attempt on its own. Contact support if repeated attempts fail and no billing or capacity problem is shown.

If you're at your plan's awake devbox limit, boxes.dev will ask you to sleep another devbox before waking this one.

The machine status menu includes sleep and automatic-wake controls. Select the image to enlarge it.

Inspect a slow or unresponsive machine

When an awake machine feels sluggish, find out what it's doing before resetting anything. Select the affected machine, then click its CPU, memory, or disk meters in the desktop titlebar to open Activity. Sort by CPU or memory to find the processes using the most resources. boxes.dev reserves some resources for its own controls, so Activity is worth trying even while a runaway process has the CPU pegged.

The titlebar's memory meter covers the whole machine, including containers and system services, and accounts for memory the system can reclaim. Hover for available memory and the sample time. Activity's Workload memory total covers managed workloads; process rows can include shared memory, so their sum may differ from either total. On a machine awaiting a service update, the titlebar tooltip may still say Workload memory.

Choose Terminate only on a process you understand; Force kill is available when a normal termination does not work. When memory runs critically low, the system may stop a Codex or Claude session to recover; reduce memory use before sending the agent back to the interrupted work.

The disk meter turns yellow below 2 GiB free and red below 1 GiB. When disk space is the problem, delete files you no longer need on the machine, or download them first if you want to keep a copy.

Activity shows running processes and their CPU and memory use. Select the image to enlarge it.

Reset a stuck machine

If the machine still misbehaves — terminals won't respond, an agent is wedged, or a service is in a bad state — reset it. Select the affected running machine, then choose Machine → Reset (stop processes)… from the desktop app's menu bar. Reset will stop shells, agents, background commands, and user services while keeping your files and the machine itself running. Read the confirmation before proceeding; boxes.dev reports what it stopped.

The Machine menu identifies the target as a Devbox with the selected thread's title or a Template box with the project name. Check that name before continuing. Reset is unavailable while the machine is sleeping; choose Wake first. Reset needs the machine's service to be running, so it cannot fix a failed wake attempt.

Afterward, reconnect your terminals and restart the services you need. The conversation stays in its thread: open it to see where the agent's work stopped, and send a follow-up to continue.

Reboot if Reset does not recover it

If Reset does not help, choose Machine → Reboot (restart machine)… from the desktop app's menu bar. Reboot works on running and sleeping machines, including a machine that cannot wake. It starts that same machine again without its saved memory. Files saved to disk remain, but changes still held only in memory may be lost. Every process and network connection stops. Existing terminals and agent sessions will not resume; reconnect your terminals, and continue a conversation by sending a follow-up in its thread. boxes.dev reports success only once the machine is running and responding again.

If reboot reports that startup failed, the machine stays sleeping; try Reboot again, or use Wake to retry a normal wake. If the machine is running but still unresponsive, wait briefly, use Reset, or contact support.

Check a recovery notice

After an unexpected stop, boxes.dev may recover the machine from a saved snapshot. A notice in the workbench will explain whether recovery restored memory or only files, and when available it also shows when that snapshot was captured, so you can judge how much recent work could be missing. Check Git, important files, and running services before dismissing the notice, and recover anything you need from Git or saved copies where you can.