Skip to main content
See Commands for usage examples.

​
attach()

attach(cmd: string, args?: Array<string>): Promise<number>
Bridge your terminal directly to a process inside the sandbox for a fully interactive PTY session. Press Ctrl+] (or configured detach keys) to disconnect without stopping the process. Parameters
NameTypeDescription
cmdstringCommand to run
args?Array<string>Command arguments
Returns
TypeDescription
numberExit code of the process

​
attachShell()

attachShell(): Promise<number>
Attach to the sandbox’s default shell. Returns
TypeDescription
numberExit code

​
attachWithConfig()

attachWithConfig(config: AttachConfig): Promise<number>
Interactive PTY attach with options for environment variables, working directory, user, and custom detach keys. Parameters
NameTypeDescription
configAttachConfigAttach configuration
Returns
TypeDescription
numberExit code

​
exec()

exec(cmd: string, args?: Array<string>): Promise<ExecOutput>
Run a command inside the sandbox and wait for it to complete. Collects all stdout and stderr into memory and returns them along with the exit code. For long-running processes or large output, use execStream() instead. Parameters
NameTypeDescription
cmdstringCommand to execute (e.g. "python", "/usr/bin/node")
args?Array<string>Command arguments (e.g. ["-c", "print('hello')"])
Returns
TypeDescription
ExecOutputCollected stdout, stderr, and exit status

​
execStream()

execStream(cmd: string, args?: Array<string>): Promise<ExecHandle>
Run a command with streaming output. Returns a handle that emits stdout, stderr, and exit events as they happen, rather than buffering everything. Parameters
NameTypeDescription
cmdstringCommand to execute
args?Array<string>Command arguments
Returns
TypeDescription
ExecHandleStreaming handle for receiving events and controlling the process

​
execWithConfig()

execWithConfig(config: ExecConfig): Promise<ExecOutput>
Run a command with per-execution overrides. Configure working directory, environment variables, timeout, stdin, and TTY allocation. These overrides apply only to this execution and don’t change the sandbox’s defaults. Parameters
NameTypeDescription
configExecConfigExecution configuration
Returns
TypeDescription
ExecOutputCollected stdout, stderr, and exit status

​
shell()

shell(script: string): Promise<ExecOutput>
Run a command through the sandbox’s configured shell (defaults to /bin/sh). Shell syntax like pipes, redirects, and && chains works. Parameters
NameTypeDescription
scriptstringShell command string (e.g. "ls -la /app && echo done")
Returns
TypeDescription
ExecOutputCollected stdout, stderr, and exit status

​
shellStream()

shellStream(script: string): Promise<ExecHandle>
Shell command with streaming output. Parameters
NameTypeDescription
scriptstringShell command string
Returns
TypeDescription
ExecHandleStreaming handle

​
Types

​
AttachConfig

FieldTypeDefaultDescription
args?Array<string>[]Command arguments
cmdstring-Command to run (required)
cwd?string-Working directory
detachKeys?stringCtrl+]Key sequence to detach without stopping
env?Record<string, string>{}Environment variables
user?string-Guest user

​
ExecConfig

Per-execution overrides.
FieldTypeDefaultDescription
args?Array<string>[]Command arguments
cmdstring-Command to execute (required)
cwd?string-Working directory
env?Record<string, string>{}Environment variables (merged on top of sandbox env)
stdin?string-Fixed stdin content
timeoutMs?number-Kill the process after this many milliseconds
tty?booleanfalseAllocate a pseudo-terminal
user?string-Guest user

​
ExecEvent

FieldTypeDescription
code?numberExit code (on 'exited')
data?BufferOutput data (on 'stdout' / 'stderr')
eventTypeExecEventTypeEvent type
pid?numberGuest PID (on 'started')

​
ExecEventType

ValueDescription
'exited'The process has exited
'started'The process has started
'stderr'A chunk of stderr data
'stdout'A chunk of stdout data

​
ExecHandle

A handle to a running streaming execution.
Property / MethodTypeDescription
collect()Promise<ExecOutput>Wait and collect all remaining output
idPromise<string>Session ID for this execution
kill()Promise<void>Send SIGKILL
recv()Promise<ExecEvent | null>Receive the next event. Returns null when done.
signal(signal)Promise<void>Send a POSIX signal to the process
takeStdin()Promise<ExecSink | null>Take the stdin writer. Returns null after first call.
wait()Promise<ExitStatus>Wait for the process to exit

​
ExecOutput

The result of a completed command execution.
Property / MethodTypeDescription
codenumberExit code
status()ExitStatusExit status object
stderr()stringCollected stderr decoded as a string
stderrBytes()BufferRaw stderr bytes
stdout()stringCollected stdout decoded as a string
stdoutBytes()BufferRaw stdout bytes
successbooleantrue if code is 0

​
ExecSink

Writer for sending data to a running process’s stdin.
MethodParametersDescription
close()-Close stdin. The process sees EOF.
write()data: BufferWrite bytes to the process’s stdin

​
ExitStatus

FieldTypeDescription
codenumberExit code. 0 typically means success.
successbooleantrue if code is 0