# Background processes

> Let an agent start long-running commands that keep running across turns, then list, inspect, read, and stop them with the builtin process tool.

Bash runs a command and waits for it to finish. Some work does not fit that model, such as a development server, a watcher, or a build that runs for minutes. The `builtin/process` tool starts such a command in the background and lets the agent check on it in later turns.

## Enable the tool

`builtin/process` is off by default. Select it explicitly in the agent’s `tools.use`.

```json
{
  "agents": {
    "dev": {
      "model": "local",
      "tools": {
        "use": [
          "builtin/read_file",
          "builtin/bash",
          "builtin/process"
        ]
      }
    }
  }
}
```

Process and Bash are separate tools with separate permission rules. Allowing one does not allow the other. Hooks and approval rules apply to each call the same way they apply to other tools.

## Actions

| Action   | Input                                                                                                           | Result                                                     |
| -------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `start`  | `command`, optional `label`, optional `cwd` relative to the session, optional `env_refs`, optional `timeout_ms` | An opaque process ID, returned once the shell has started. |
| `list`   | None                                                                                                            | The processes in the session.                              |
| `status` | The process ID                                                                                                  | The process state and exit details.                        |
| `output` | The process ID and a cursor                                                                                     | A page of recent output.                                   |
| `stop`   | The process ID                                                                                                  | Stops the process.                                         |

The agent refers to a process only by the ID that `start` returns. It never uses an operating-system process ID.

A successful `start` means the shell was launched. It does not mean the program is ready. Use `output` to check for a ready message.

## States

| State       | Meaning                                                      |
| ----------- | ------------------------------------------------------------ |
| `starting`  | Raw has reserved the process and is launching it.            |
| `running`   | The process is running.                                      |
| `stopping`  | A stop was requested and the process is shutting down.       |
| `exited`    | The process exited with code `0`.                            |
| `failed`    | The process exited with a nonzero code.                      |
| `stopped`   | The process was stopped by a request.                        |
| `timed_out` | The process reached its `timeout_ms` deadline.               |
| `lost`      | The host that owned the process stopped without cleaning up. |

`stop` is idempotent. Stopping a process that has already finished returns its final state.

## Output

- Each process keeps up to 1 MiB of its most recent output. Stdout and stderr are labeled.
- A page returns up to 64 KiB.
- Cursors are byte positions in the output. Each response reports the earliest available position and the next cursor.
- When old output has been dropped, a cursor that points before it resumes at the earliest retained output, and the response says so.
- A page that is too small to hold the next UTF-8 character returns an error rather than a cursor that cannot advance.

## Limits

| Scope                             | Limit |
| --------------------------------- | ----- |
| Live processes per session        | 8     |
| Live processes per host           | 32    |
| Finished records kept per session | 100   |

## Ownership and lifetime

The host that runs the session owns the process supervisor. That host is the CLI, the dashboard server, or an ACP connection.

- A process started successfully keeps running after the turn that started it ends. It also keeps running if you close the browser tab.
- A start that is cancelled before Raw confirms it is stopped.
- A process ends on its own, at its deadline, on `stop`, when its session is deleted, or when its host shuts down.
- On shutdown, Raw stops the process group with `TERM`, then `KILL` if needed. Processes that detached from the group are not covered by this guarantee.
- If the host crashes, Raw marks its processes as `lost` the next time it looks at them. Raw does not signal or reattach to a process from a dead host, and it does not restart a command.

Managed processes are supported on macOS and Linux. On Windows, `start` returns `unsupported_platform` without starting anything. Foreground Bash keeps its existing behavior on every platform.

> **Caution:**
>
> A background process has your full OS account permissions, the same as Bash. Use `tools.rules` to ask before `start` if you want a review step.

## In the dashboard

The dashboard’s **Commands** section lists foreground Bash commands and background processes together. You can read a process’s output there and stop it, even while a model turn is running. Stopping from the dashboard goes through the same policy and approval checks as a model call.

## Related

- [Tools](https://raw.tlelabs.com/docs/extend/tools/) covers the other built-in tools and tool rules.
- [Configuration reference](https://raw.tlelabs.com/docs/reference/configuration/) lists the agent fields.