Process descriptor | Doc Detective

Referenced In

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

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