Skip to main content
See Commands for usage examples.

​
Types

​
ExecOutput

The result of a completed command execution.
PropertyTypeDescription
exit_codeintExit code
successboolTrue if exit_code is 0
stdout_textstrCollected stdout decoded as UTF-8. Raises on invalid encoding.
stderr_textstrCollected stderr decoded as UTF-8
stdout_bytesbytesRaw stdout bytes
stderr_bytesbytesRaw stderr bytes

​
ExecHandle

A handle to a running streaming execution. Supports async for event in handle: to iterate over events until the stream ends.
Property / MethodTypeDescription
idstrCorrelation ID for this execution
take_stdin()ExecSink | NoneTake the stdin writer. Returns None after first call.
recv()ExecEvent | None(async) Receive the next event. Returns None when done.
wait()tuple[int, bool](async) Wait for the process to exit. Returns (code, success).
collect()ExecOutput(async) Wait and collect all remaining output
signal(sig)None(async) Send a POSIX signal to the process
kill()None(async) Send SIGKILL

​
ExecSink

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

​
ExecEvent

Low-level event from PyO3 bindings.
PropertyTypeDescription
event_typestr"started", "stdout", "stderr", or "exited"
pidint | NoneGuest PID (on "started")
databytes | NoneOutput data (on "stdout" / "stderr")
codeint | NoneExit code (on "exited")
Python dataclass variants are also available for pattern matching:
ClassFieldsDescription
StartedEventpid: intThe process has started
StdoutEventdata: bytesA chunk of stdout data
StderrEventdata: bytesA chunk of stderr data
ExitedEventcode: intThe process has exited
The union type ExecEvent = StartedEvent | StdoutEvent | StderrEvent | ExitedEvent is available from events.py.

​
ExecOptions

ExecOptions(
    args: tuple[str, ...] = (),
    cwd: str | None = None,
    user: str | None = None,
    env: Mapping[str, str] = {},
    timeout: float | None = None,  # seconds
    stdin: Stdin = Stdin.null(),
    tty: bool = False,
    rlimits: tuple[Rlimit, ...] = (),
)
Frozen dataclass for per-execution overrides.
FieldTypeDefaultDescription
argstuple[str, ...]()Command arguments
cwdstr | NoneNoneWorking directory
userstr | NoneNoneGuest user
envMapping[str, str]{}Environment variables
timeoutfloat | NoneNoneKill the process after this many seconds
stdinStdinStdin.null()Stdin source
ttyboolFalseAllocate a pseudo-terminal
rlimitstuple[Rlimit, ...]()Resource limits

​
AttachOptions

AttachOptions(
    args: tuple[str, ...] = (),
    cwd: str | None = None,
    user: str | None = None,
    env: Mapping[str, str] = {},
    detach_keys: str | None = None,
)
Frozen dataclass for interactive PTY attach configuration.
FieldTypeDefaultDescription
argstuple[str, ...]()Command arguments
cwdstr | NoneNoneWorking directory
userstr | NoneNoneGuest user
envMapping[str, str]{}Environment variables
detach_keysstr | NoneNoneKey sequence to detach without stopping

​
Stdin

Frozen dataclass with factory methods for configuring process stdin.
FactoryParametersDescription
Stdin.null()-/dev/null (default)
Stdin.pipe()-Piped stdin. Use take_stdin() on the handle to write.
Stdin.bytes()data: bytesInline data sent before the process starts

​
Rlimit

Frozen dataclass with factory methods for POSIX resource limits.
FactoryParametersDescription
Rlimit.nofile(limit)limit: intMax open file descriptors
Rlimit.cpu(secs)secs: intCPU time limit in seconds
Rlimit.as_(*, soft, hard)soft: int, hard: intVirtual memory size
Rlimit.nproc(limit)limit: intMax number of processes
Rlimit.fsize(limit)limit: intMax file size
Rlimit.memlock(limit)limit: intMax locked memory
Rlimit.stack(limit)limit: intMax stack size
Properties
PropertyTypeDescription
resourceRlimitResourceResource type
softintSoft limit
hardintHard limit

​
RlimitResource

Enum of POSIX resource types.
ValueDescription
cpuCPU time
fsizeFile size
dataData segment size
stackStack size
coreCore file size
rssResident set size
nprocNumber of processes
nofileOpen file descriptors
memlockLocked memory
asVirtual memory
locksFile locks
sigpendingPending signals
msgqueueMessage queue size
niceNice priority ceiling
rtprioReal-time priority ceiling
rttimeReal-time CPU time

​
SandboxMetrics

Metrics snapshot for a running sandbox.
PropertyTypeDescription
cpu_percentfloatCPU utilization percentage
memory_bytesintCurrent memory usage in bytes
memory_limit_bytesintMemory limit in bytes
disk_read_bytesintTotal bytes read from disk
disk_write_bytesintTotal bytes written to disk
net_rx_bytesintTotal bytes received over the network
net_tx_bytesintTotal bytes sent over the network
uptime_msintSandbox uptime in milliseconds
timestamp_msfloatTimestamp of the snapshot in milliseconds

​
MetricsStream

Async iterator yielding SandboxMetrics. Use async for metrics in stream: to consume.