Retrieves detailed information about a specific background process by its ID.
Method Signature
await sandbox.getProcess(
id: string,
sessionId?: string
): Promise<Process | null>
Parameters
The process ID to retrieve
Optional session ID. If not provided, the default session is used.
Returns
Process object if found, or null if the process doesn’t exist
Unique process identifier
System process ID (if available and running)
Command that was executed
Current process status: 'starting' | 'running' | 'completed' | 'failed' | 'killed' | 'error'
When the process was started
When the process ended (if completed)
Process exit code (if completed)
kill
(signal?: string) => Promise<void>
Kill the process
getStatus
() => Promise<ProcessStatus>
Get current process status (refreshed)
getLogs
() => Promise<{ stdout: string; stderr: string }>
Get accumulated logs
waitForLog
(pattern: string | RegExp, timeout?: number) => Promise<WaitForLogResult>
Wait for a log pattern to appear in process output
waitForPort
(port: number, options?: WaitForPortOptions) => Promise<void>
Wait for a port to become ready
waitForExit
(timeout?: number) => Promise<WaitForExitResult>
Wait for the process to exit
Examples
Get process by ID
const process = await sandbox.getProcess('dev-server');
if (process) {
console.log('Status:', process.status);
console.log('Started:', process.startTime);
} else {
console.log('Process not found');
}
Check if process is running
const process = await sandbox.getProcess('my-process');
if (process && process.status === 'running') {
console.log('Process is running with PID:', process.pid);
}
Get exit code of completed process
const process = await sandbox.getProcess('batch-job');
if (process && process.status === 'completed') {
console.log('Process completed with exit code:', process.exitCode);
}