host.process
Query client processes, run commands, and control streaming child processes.
The process interface queries processes, runs shell commands, and controls child processes with streaming input and output on the selected client.
Here, host is a selected RemoteHost; see host discovery to obtain one. The module overview covers permissions and shared errors.
Queries require process.enabled. exec() and spawn() additionally require process.allow_exec.
host.process.list()
Function: obtains a PID-sorted process snapshot.
Parameters: none.
Return value: AsyncIterableIterator<ProcessInfo>. Sampling occurs on the first next(); exhaustion, return(), or break releases the snapshot.
host.process.get(pid)
Function: queries a specific process.
Parameters: required pid: number, the process ID.
Return value: Promise<ProcessInfo | null>. An absent or no-longer-visible process returns null.
ProcessInfo
| Field | Type | Description |
|---|---|---|
pid | number | Process ID |
parentPid | number / null | Parent process ID |
name, exe, status | string / null | Name, executable path, and status |
commandLine | readonly string[] / null | Command-line arguments |
startTime | Date / null | Process start time on the client |
cpuUsage | number / null | CPU percentage; one fully utilized logical core is 100 |
memoryBytes | number / null | Resident memory in bytes |
Fields are read-only; unavailable information is null.
host.process.exec(command)
Function: executes a shell command, automatically sends stdin EOF, and collects complete stdout and stderr.
Parameters: required command: string. Commands inherit the client's working directory, environment, and system user permissions. Linux / macOS use /bin/sh -c; Windows uses cmd.exe /d /s /c.
Return value: Promise<ProcessResult>, containing stdout: Uint8Array, stderr: Uint8Array, exitCode: number | null, and signal: number | null. Nonzero exit codes are returned without automatically throwing. signal is the Unix signal number, or null for normal exits and on Windows.
host.process.spawn(command)
Function: starts a shell child process with streaming input and output. Working directory, environment, and shell rules match exec().
Parameters: required command: string.
Return value: Promise<ChildProcess>, with these read-only properties and a kill() method.
| Property | Type | Description |
|---|---|---|
pid | number | Child process ID |
commandLine | string | Submitted command |
stdout, stderr | ReadableStream<Uint8Array> | Raw byte output with backpressure; canceling one closes only that output pipe |
stdin | WritableStream<Uint8Array> | Closing its writer sends EOF; abort closes the input pipe |
status | Promise<ProcessStatus> | { exitCode: number | null, signal: number | null }, with the same meaning as exec |
Consume stdout and stderr concurrently and close the stdin writer when done. Waiting only for status can block on full output pipes. Drain remaining output even after status resolves. The process cursor is released after status, both outputs, and submitted input operations complete; the last completing operation can report cleanup failure.
child.kill()
Function: forcefully stops the child process group or job and waits for the child to be reaped. Descendants can still be stopped after status resolves until cursor release.
Parameters: none.
Return value: Promise<void>.
See remote.d.ts for type declarations.