Process

Process runs commands and code inside a sandbox, and manages long-running background sessions. Obtain it as sandbox.process — see the running commands guide for a task-oriented walkthrough.

executeCommand()

Executes a shell command inside the sandbox and waits for it to finish.

executeCommand(
  command: string,
  cwd?: string,
  env?: Record<string, string>,
  timeout?: number,
): Promise<ExecuteResponse>

Returns: ExecuteResponse with exitCode: number, result: string (combined output), and artifacts: { stdout: string }.

const result = await sandbox.process.executeCommand('ls -la', '/tmp', undefined, 30)
console.log(result.exitCode, result.result)

codeRun()

Executes a code string using the sandbox's configured language runtime. The language comes from the code-toolbox-language label set at sandbox creation; without it this throws an Error.

codeRun(code: string, params?: CodeRunParams, timeout?: number): Promise<ExecuteResponse>

Returns: ExecuteResponse (same shape as executeCommand). Throws: Error when the sandbox has no configured code language.

const result = await sandbox.process.codeRun('console.log([1, 2, 3].length)')
console.log(result.result) // 3

Sessions

Sessions are long-running background shells: create one, execute commands in it (synchronously or async), fetch logs, send input, and delete it when done. State (working directory, environment) persists between commands in the same session.

createSession()

Creates a new background session with the id you choose.

createSession(sessionId: string): Promise<void>

getSession()

Fetches a session and its command history.

getSession(sessionId: string): Promise<Session>

Returns: Session — { sessionId, commands?: Command[] } where Command is { id?, command?, exitCode? }.

listSessions()

Lists all active sessions in the sandbox.

listSessions(): Promise<Session[]>

executeSessionCommand()

Executes a command inside an existing session. With runAsync: true in the request, the call returns immediately with a command id you can poll via getSessionCommand() / getSessionCommandLogs().

executeSessionCommand(
  sessionId: string,
  req: SessionExecuteRequest,
  timeout?: number,
): Promise<SessionExecuteResponse>

Returns: SessionExecuteResponse — { cmdId, exitCode?, output?, stdout, stderr } (stdout/stderr default to '').

await sandbox.process.createSession('build')
const res = await sandbox.process.executeSessionCommand('build', {
  command: 'make -j4',
  runAsync: true,
})
const logs = await sandbox.process.getSessionCommandLogs('build', res.cmdId)

getSessionCommand()

Fetches metadata (command line, exit code) for one command previously executed in a session.

getSessionCommand(sessionId: string, commandId: string): Promise<Command>

getSessionCommandLogs()

Fetches the accumulated logs of a session command.

getSessionCommandLogs(sessionId: string, commandId: string): Promise<SessionCommandLogsResponse>

Returns: { output, stdout, stderr } (each defaulted to '').

sendSessionCommandInput()

Sends input to a running session command's stdin — for interactive programs awaiting input.

sendSessionCommandInput(sessionId: string, commandId: string, input: string): Promise<void>

deleteSession()

Deletes a session and terminates anything still running in it.

deleteSession(sessionId: string): Promise<void>