> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.doc-detective.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server.

# Process descriptor

> Reference for the `Process descriptor` schema.

## Referenced In

* [startSurface](/reference/schemas/startsurface)

## Fields

| Field            | Type            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Default |
| :--------------- | :-------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| process          | string          | Required. Shell command to start as a long-running background process (same shell semantics as runShell: pipes, `&&`, globbing, environment-variable expansion). Equivalent to a `runShell` step with `background` — both forms remain valid. Minimum length: 1. Pattern: `\S`                                                                                                                                                                                                                                                                                                                                                                               | —       |
| name             | string          | Required. Surface-registry name later steps use in `surface`, and the handle a closeSurface step stops. Unique across all open surfaces. Minimum length: 1. Pattern: `\S`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | —       |
| args             | array of string | Optional. Arguments for the command.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `[]`    |
| workingDirectory | string          | Optional. Working directory for the process.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `.`     |
| tty              | boolean         | Optional. Run the process in a pseudo-terminal (PTY) instead of a pipe, so full-screen/interactive TUIs (those that check `isTTY`) render and accept keystrokes. Requires the PTY backend `@homebridge/node-pty-prebuilt-multiarch` to be installed (`npm install @homebridge/node-pty-prebuilt-multiarch`); it is not bundled, and if it is unavailable the descriptor is skipped. `stdout` and `stderr` are merged into one stream in PTY mode. PTY output includes raw ANSI escape sequences (colors, cursor movement); `waitUntil.stdio` patterns should target text that renders without interleaved control codes, or use a regex that tolerates them. | `false` |
| waitUntil        | object          | Optional. Conditions that must all be met before the process is considered ready and the descriptor completes. Omit to consider the process ready as soon as it is spawned. Specify any combination; every condition given must pass before `timeout` elapses. Note: a process that forks a daemon and then exits (common for some Docker images and databases) is treated as having exited before becoming ready and the descriptor fails — use `port`, `httpGet`, or `delayMs` for those rather than a condition that depends on the foreground process staying alive.                                                                                     | —       |
| timeout          | integer         | Optional. Max time in milliseconds to wait for `waitUntil` before the descriptor fails. Minimum: 0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `60000` |

## Examples

```json
{
  "process": "example",
  "name": "example",
  "args": [],
  "workingDirectory": ".",
  "tty": false,
  "timeout": 60000
}
```