Background processes

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.

{
  "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.

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.

Tools covers the other built-in tools and tool rules.
Configuration reference lists the agent fields.