> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Running long tasks

> Keep a Devbox running while a build, test suite, or agent works, and clean up afterwards.

A Devbox stops automatically once it has been inactive for the length of its [idle timeout](/docs/devbox/managing#idleness--auto-stop). 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`.

<h2 id="task-markers">
  Keep a Devbox running
</h2>

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](/docs/devbox/sessions).

<Steps titleSize="h3">
  <Step title="Create a marker">
    Create a file under `/.namespace/tasks` before the work begins:

    ```bash theme={null}
    touch /.namespace/tasks/my-long-running-task
    ```

    <Tip>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`.</Tip>
  </Step>

  <Step title="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.
  </Step>

  <Step title="Remove the marker">
    Remove the file once the work finishes:

    ```bash theme={null}
    rm -f /.namespace/tasks/my-long-running-task
    ```

    This restarts the idle countdown, so the Devbox stops once the timeout elapses with no other activity.
  </Step>
</Steps>

<h2 id="agents">
  Have an agent mark its own work
</h2>

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:

```text wrap Agent Prompt theme={null}
Before starting long-running work, create a marker file under /.namespace/tasks named after the task, and delete it when the work is done, including if it fails.
```

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.

<h2 id="cleanup">
  Clean up leftover markers
</h2>

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:

<Tabs>
  <Tab title="List markers">
    See which markers are currently in place:

    ```bash theme={null}
    ls /.namespace/tasks
    ```

    An empty directory means no marker is keeping the Devbox running.
  </Tab>

  <Tab title="Remove marker">
    Remove a marker that does not belong to work still in progress:

    ```bash theme={null}
    rm -f /.namespace/tasks/my-long-running-task
    ```
  </Tab>

  <Tab title="Remove all markers">
    Clear every marker at once:

    ```bash theme={null}
    rm -f /.namespace/tasks/*
    ```
  </Tab>
</Tabs>

Removing the last marker restarts the idle countdown, so the Devbox stops once the timeout elapses with no other activity.

<Tip>
  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:

  ```bash theme={null}
  touch /.namespace/tasks/my-long-running-task
  trap 'rm -f /.namespace/tasks/my-long-running-task' EXIT
  ```
</Tip>

<h2 id="with-exec">
  Mark work from your own machine
</h2>

You do not have to be inside the Devbox to manage a marker. [`devbox exec`](/docs/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:

<Tabs>
  <Tab title="Add marker">
    Create the marker before the work begins:

    ```bash theme={null}
    devbox exec my-devbox -- touch /.namespace/tasks/my-long-running-task
    ```
  </Tab>

  <Tab title="Remove marker">
    Remove it once the work finishes:

    ```bash theme={null}
    devbox exec my-devbox -- rm -f /.namespace/tasks/my-long-running-task
    ```
  </Tab>
</Tabs>

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](/docs/devbox/exec#detached-executions), 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.

## Related topics

<CardGroup cols={2}>
  <Card title="Managing Devboxes" icon="timer" href="/docs/devbox/managing#idleness--auto-stop">
    Configure the idle timeout and see which signals count as activity.
  </Card>

  <Card title="Agents on Devboxes" icon="bot" href="/docs/devbox/agents">
    Run coding agents inside a Devbox.
  </Card>
</CardGroup>