Skip to main content
A Devbox stops automatically once it has been inactive for the length of its idle timeout. Because activity is measured by connections and sessions rather than by load, a long build or an agent working through a large task can be interrupted before it finishes, whether you started it with devbox exec or from inside a session. The solution is to tell the Devbox that work is in progress, by creating a file under /.namespace/tasks.

​
Keep a Devbox running

A file under /.namespace/tasks acts as a task marker. While any marker exists, the Devbox is treated as active and the idle countdown does not start. The steps below run inside the Devbox, in a shell opened with devbox ssh or in a session.
1

Create a marker

Create a file under /.namespace/tasks before the work begins:
The name is yours to choose. Use something that identifies the work, because a marker left behind is easier to trace to its owner than a file called task.
2

Run the work

For example, start the build, test suite, or agent task as you normally would.The Devbox stays running for as long as the marker is in place, whether or not anything is connected to it.
3

Remove the marker

Remove the file once the work finishes:
This restarts the idle countdown, so the Devbox stops once the timeout elapses with no other activity.

​
Have an agent mark its own work

An agent working unattended is the case this matters most for: it holds no SSH connection of its own, and a long task can outlast the idle timeout. Ask the agent to create a marker while it works:
Agent Prompt
Putting the same instruction in the repository’s agent instructions file, such as AGENTS.md or CLAUDE.md, applies it to every session without repeating the prompt.

​
Clean up leftover markers

A marker does not expire, and it survives a restart. If one is never removed, because the work failed before its cleanup ran or the process was killed, the Devbox is treated as active indefinitely and never stops on idle. Stopping it with devbox stop still works, but the idle timeout no longer does anything for it. Inspect and clear markers from a shell in the Devbox:
See which markers are currently in place:
An empty directory means no marker is keeping the Devbox running.
Removing the last marker restarts the idle countdown, so the Devbox stops once the timeout elapses with no other activity.
To avoid leaving markers behind in the first place, remove them with a shell trap so cleanup runs on failure and interruption as well as on success:

​
Mark work from your own machine

You do not have to be inside the Devbox to manage a marker. devbox exec runs a single command in the Devbox and returns, so the same touch and rm work from your local shell or from a script on your machine:
Create the marker before the work begins:
Use this when the work spans several commands, or several executions, and you are driving them from outside. It is also what protects a detached execution, which keeps running after your CLI exits but ends if the Devbox stops. Because each command is a separate execution, nothing removes the marker for you. Anything that stops you before the last command leaves it in place.

Managing Devboxes

Configure the idle timeout and see which signals count as activity.

Agents on Devboxes

Run coding agents inside a Devbox.
Last modified on September 8, 2026