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. Sleeping machines use no active box-hours and release awake capacity, while awake Template boxes and devboxes count against your plan's box-hours.

An agent's background work can also keep its devbox awake after the reply finishes. In the chat view, Claude background subagents keep it awake while they work, including while they wait on a tool. After 12 minutes without new activity, normal idle sleep can resume.

Codex background commands and Claude subagents started in a terminal receive up to one hour of sleep protection. Claude background commands and workflows use their declared timeout, capped at four hours, or one hour when no timeout is declared. Finishing the work releases that protection sooner. When the limit expires, normal idle sleep can resume; the limit does not terminate the command. You can still sleep the devbox yourself.

Claude's background shell commands in the chat view have a separate execution limit: 30 minutes by default, up to two hours. When that limit expires, Claude stops the command and receives a notification.

A boxes.dev update can restart Claude, which stops its running background commands. boxes.dev will then send the agent a message in the thread that lists the stopped commands, so it can check their work and restart any it still needs.

To change the timeout for your Template boxes and devboxes, open Account → Sleep timeout and choose 5, 15, 30, or 60 minutes. Longer timeouts will keep your apps available between visits and use more box-hours. Choose Team default to follow your team's setting; team admins can change that default in Team settings → Sleep timeout. Without a custom setting, the default is five minutes.

Changes apply to existing and new boxes. A running box may keep its current sleep deadline until its next activity; saving will not wake a sleeping box. Active agents can still keep boxes awake, and you can still sleep a box yourself.

Traffic to your app through desktop localhost forwarding doesn't count as activity, so a box can sleep while you test in a browser. To keep it awake, open the status menu in the desktop titlebar, choose Keep awake, and pick 1, 2, or 4 hours. A lightning icon will show next to the box's name until that time. The box will use box-hours the whole time, even while idle, and your plan's billing limits still apply. To let it sleep sooner, choose Keep awake → Turn off; sleeping or rebooting the box yourself also turns it off. Once it's off, the box will sleep after the usual timeout unless other activity keeps it awake.

Automatic waking is on by default, so a sleeping box will normally wake when you return to its thread or Template box page. To change this, use Wake sleeping boxes automatically in the titlebar's 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.

Ask an agent to check later

For work that can wait, ask the agent to check again at a particular time. It can save one check in the current thread, from one minute to 24 hours ahead, and let the box sleep meanwhile. For example, ask it to inspect the status of an existing deployment in ten minutes, without starting another deployment.

At the requested time, boxes.dev will try to wake the box and start the saved prompt when the thread is idle. Your queued messages take priority. If the check cannot start within 30 minutes, a notice will explain what happened. Your plan's awake-capacity, billing and sign-in requirements still apply. The timer records a request to check; it does not promise the work will finish by that time.

When a local command must keep running, the agent can instead request that the box stay awake. Each request lasts 20 minutes by default and can last up to four hours. Awake time uses box-hours even when the box is mostly idle, and larger boxes use more. The thread will show the estimated usage. Agent responses can also use your model allowance. Frequent checks can keep a box awake continuously if their work and the normal sleep timeout overlap.

A box that has stayed awake for 24 hours in a row will pause briefly. If it still has work in progress or an active keep-awake request, it will usually resume on its own within seconds, as long as your plan's billing status and awake devbox limit allow it. Running commands continue where they left off, but network connections may need to reconnect.

A timer or power icon at the right of the thread row marks its saved request. Open the thread to see the reason and time above the message box. Choose Cancel to cancel the displayed check or keep-awake request. Cancellation does not require the box to be awake. On desktop, turn automatic waking off to open the thread and cancel while the box stays asleep. Opening a thread on mobile can wake its box before you cancel. If a check is already starting, open its thread and use Stop to interrupt the response. Stop alone does not cancel future checks or keep-awake requests. Existing Claude-native timers are shown read-only; ask the agent to inspect that timer in its thread.

The desktop power menu lists which threads are keeping the box awake and when its next check is scheduled. Select a line to open the responsible thread. Before sleeping the box, check the menu's reminder: keep-awake requests will end, but a saved check can wake it later.

Cancelling a keep-awake request or reaching its deadline allows normal sleep again. It does not terminate the command, stop another thread's work, or make the whole box sleep immediately. Sleeping, resetting or rebooting the box yourself will end its keep-awake requests. Saved checks remain after sleep or reboot and can wake it later; the power menu shows the next check. Archiving or deleting a thread, or destroying its box, cancels its pending requests. Snapshots do not copy requests to new devboxes.

If a notice says the check's delivery could not be confirmed, inspect the thread before asking for another attempt. boxes.dev will not automatically resend an uncertain check. Dismiss the notice once you have checked what ran.

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 box 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, and background commands while keeping your files and the machine itself running. Services set to always restart will start again. 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.