Starts a long-running background process in the sandbox. Use this for servers, services, and any command that should continue running after the initial call returns.
Method Signature await sandbox . startProcess ( command : string , options ?: ProcessOptions , sessionId ?: string ): Promise < Process >
Parameters The command to execute as a background process "python -m http.server 8080"
Configuration options for the process Custom process ID for later reference. If not provided, a UUID will be generated.
Maximum execution time in milliseconds
env
Record<string, string | undefined>
Environment variables for this process. Values temporarily override session-level env vars.
Working directory for the process
Automatically cleanup process record after exit
onExit
(code: number | null) => void
Callback when process exits
onOutput
(stream: 'stdout' | 'stderr', data: string) => void
Callback for real-time output
onStart
(process: Process) => void
Callback when process starts successfully
Callback for process errors
Optional session ID. If not provided, the default session is used.
Returns A Process object with methods for interacting with the running process 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 Start a web server const process = await sandbox . startProcess ( 'python -m http.server 8080' ); console . log ( 'Server started:' , process . id );
Start with custom process ID const process = await sandbox . startProcess ( 'npm run dev' , { processId: 'dev-server' } );
Monitor process output const process = await sandbox . startProcess ( 'python train.py' , { onOutput : ( stream , data ) => { console . log ( `[ ${ stream } ]:` , data ); }, onExit : ( code ) => { console . log ( 'Process exited with code:' , code ); } } );
Start with environment variables const process = await sandbox . startProcess ( 'node server.js' , { env: { PORT: '3000' , NODE_ENV: 'production' } } );