Python SDK Execution reference

See Commands for usage examples.

Sandbox

sandbox.exec()

async def exec(
    cmd: str,
    args: list[str] | ExecOptions | None = None,
    *,
    cwd: str | None = None,
    user: str | None = None,
    env: Mapping[str, str] | None = None,
    timeout: float | None = None,
    stdin: Stdin | bytes | None = None,
    tty: bool = False,
    rlimits: list[Rlimit] | None = None,
) -> ExecOutput

Example

out = await sandbox.exec(
    "python3",
    ["script.py"],
    cwd="/app",
    env={"PYTHONPATH": "/app/lib"},
    timeout=30.0,
)
print(out.stdout_text)
print(out.exit_code)  # 0

Run a command inside the sandbox and wait for it to complete, buffering all stdout and stderr into memory. The keyword-only options apply to this call alone and don’t change the sandbox’s defaults. For long-running processes or large output, use exec_stream() instead. Raises ExecTimeoutError if timeout elapses and MicrosandboxError if the process can’t be spawned.

Parameters

cmdstr

Command to execute (e.g. “python3”, “/usr/bin/node”).

argslist[str] | ExecOptions | None

Command arguments, or a typed options mapping that may include its own args list.

cwdstr | None

Working directory for this command.

userstr | None

Guest user to run as.

envMapping[str, str] | None

Environment variables, merged on top of the sandbox defaults.

timeoutfloat | None

Seconds before the process is killed.

stdinStdin | bytes | None

Stdin configuration. Raw bytes are sent inline; default is /dev/null.

ttybool

Allocate a pseudo-terminal, merging stdout and stderr.

rlimitslist[Rlimit] | None

POSIX resource limits applied to the process.

Returns

ExecOutput

Collected stdout, stderr, and exit status.

sandbox.shell()

async def shell(
    script: str,
    *,
    cwd: str | None = None,
    user: str | None = None,
    env: Mapping[str, str] | None = None,
    timeout: float | None = None,
    stdin: Stdin | bytes | None = None,
    tty: bool = False,
    rlimits: list[Rlimit] | None = None,
) -> ExecOutput

Example

out = await sandbox.shell("ls -la /app && echo done")
print(out.stdout_text)

Run a command through the sandbox’s configured shell (defaults to /bin/sh). Shell syntax like pipes, redirects, and && chains works. Accepts the same keyword-only options as exec().

Parameters

scriptstr

Shell command string (e.g. “ls -la /app && echo done”).

cwd, user, env, timeout, stdin, tty, rlimits

Same per-call options as exec().

Returns

ExecOutput

Collected stdout, stderr, and exit status.

Stream methods

sandbox.exec_stream()

async def exec_stream(
    cmd: str,
    args: list[str] | ExecOptions | None = None,
    *,
    cwd: str | None = None,
    user: str | None = None,
    env: Mapping[str, str] | None = None,
    timeout: float | None = None,
    stdin: Stdin | bytes | None = None,
    tty: bool = False,
    rlimits: list[Rlimit] | None = None,
) -> ExecHandle

Example

import sys

from microsandbox import ExecEventType

handle = await sandbox.exec_stream("tail", ["-f", "/var/log/app.log"])
async for event in handle:
    if event.event_type is ExecEventType.STDOUT:
        sys.stdout.buffer.write(event.data)
    elif event.event_type is ExecEventType.EXITED:
        break

Run a command with streaming output. Returns an ExecHandle that emits stdout, stderr, and exit events as they happen rather than buffering everything. Takes the same per-call options as exec(). Pass stdin=Stdin.pipe() to write to the process while it runs via take_stdin(). For TTY sessions, call resize(rows, cols) when the terminal dimensions change.

Parameters

cmdstr

Command to execute.

argslist[str] | ExecOptions | None

Command arguments, or a typed options mapping.

cwd, user, env, timeout, stdin, tty, rlimits

Same per-call options as exec().

Returns

ExecHandle

Streaming handle for receiving events and controlling the process.

sandbox.shell_stream()

async def shell_stream(
    script: str,
    *,
    cwd: str | None = None,
    user: str | None = None,
    env: Mapping[str, str] | None = None,
    timeout: float | None = None,
    stdin: Stdin | bytes | None = None,
    tty: bool = False,
    rlimits: list[Rlimit] | None = None,
) -> ExecHandle

Example

import sys

from microsandbox import ExecEventType

handle = await sandbox.shell_stream("for i in 1 2 3; do echo $i; sleep 1; done")
async for event in handle:
    if event.event_type is ExecEventType.STDOUT:
        sys.stdout.buffer.write(event.data)

Streaming variant of shell(): runs script through the configured shell but returns an ExecHandle instead of buffering output.

Parameters

scriptstr

Shell command string.

cwd, user, env, timeout, stdin, tty, rlimits

Same per-call options as exec().

Returns

ExecHandle

Streaming handle.

Attach methods

sandbox.attach()

async def attach(
    cmd: str,
    args: list[str] | None = None,
    *,
    cwd: str | None = None,
    user: str | None = None,
    env: Mapping[str, str] | None = None,
    detach_keys: str | None = None,
) -> int

Example

code = await sandbox.attach("bash", cwd="/app", env={"EDITOR": "vim"})

Bridge your terminal directly to a process inside the sandbox for a fully interactive PTY session. Press the configured detach key sequence (default Ctrl+]) to disconnect without stopping the process. Returns the process exit code.

Parameters

cmdstr

Command to run.

argslist[str] | None

Command arguments.

cwdstr | None

Working directory.

userstr | None

Guest user to run as.

envMapping[str, str] | None

Environment variables for the session.

detach_keysstr | None

Detach key sequence (e.g. “ctrl-]” or “ctrl-p,ctrl-q”).

Returns

int

Exit code of the process.

sandbox.attach_shell()

async def attach_shell() -> int

Example

code = await sandbox.attach_shell()

Bridge your terminal to the sandbox’s default shell in a fully interactive PTY session. Returns the shell’s exit code.

Returns

int

Exit code of the shell process.

ExecHandle

Returned by exec_stream() · shell_stream()

A handle to a running streaming execution and its events.

handle.id

str Correlation ID for this execution

handle.take_stdin()

take_stdin()

Take the stdin writer. Returns None after the first call, or when stdin wasn’t piped

Returns

ExecSink \| None

handle.recv()

recv()

(async) Receive the next event. Returns None when the stream ends

Returns

ExecEvent \| None

handle.wait()

wait()

(async) Wait for the process to exit. Returns (code, success)

Returns

tuple[int, bool]

handle.collect()

collect()

(async) Drain remaining output and wait for exit

Returns

ExecOutput

handle.signal()

signal(sig)

(async) Send a POSIX signal (numeric) to the process

handle.kill()

kill()

(async) Send SIGKILL to the process

handle.resize()

resize(rows, cols)

(async) Resize the PTY to the given uint16 dimensions

ExecSink

Returned by ExecHandle.take_stdin()

Writer for sending data to a running process’s stdin. Obtained from ExecHandle.take_stdin() when the execution was configured with stdin=Stdin.pipe().

sink.write()

write(data)

(async) Write bytes to the process’s stdin

sink.close()

close()

(async) Close the sink. Sends EOF in non-TTY pipe mode; the guest PTY remains open in TTY mode

Stdin

Used by exec() · shell() · exec_stream() · shell_stream()

Factory for process stdin configuration.

Stdin.null()

Stdin.null()

Connect stdin to /dev/null (default)

Stdin.pipe()

Stdin.pipe()

Open a writable pipe. Write via take_stdin() on the handle

Stdin.bytes()

Stdin.bytes(data)

Inline data sent before the process starts, then EOF The factories set the corresponding StdinMode member.

Rlimit

Used by exec() · shell() · exec_stream() · shell_stream()

Frozen dataclass describing a POSIX resource limit. Construct one directly or via a factory, then pass a list as the rlimits argument.

Field	Type	Description
`resource`	`RlimitResource`	Which resource is limited
`soft`	`int`	Soft limit
`hard`	`int`	Hard limit

Rlimit.nofile()

Rlimit.nofile(limit)

Max open file descriptors

Rlimit.cpu()

Rlimit.cpu(secs)

CPU time limit in seconds

Rlimit.as_()

Rlimit.as_(\*, soft, hard)

Virtual memory size

Rlimit.nproc()

Rlimit.nproc(limit)

Max number of processes

Rlimit.fsize()

Rlimit.fsize(limit)

Max file size

Rlimit.memlock()

Rlimit.memlock(limit)

Max locked memory

Rlimit.stack()

Rlimit.stack(limit)

Max stack size

Types

ExecOptions

Accepted by exec() · exec_stream()

Typed dictionary for passing arguments and per-call options together as the second positional argument. Use a Stdin object to select a mode or raw bytes for inline data.

Key	Type	Description
args	`list[str]`	Command arguments
cwd	`str`	Working directory
user	`str`	Guest user
env	`Mapping[str, str]`	Per-command environment variables
timeout	`float`	Timeout in seconds
stdin	`Stdin` `\| bytes`	Stdin configuration or inline bytes
stdin_data	`bytes`	Inline stdin bytes when `stdin` is omitted
tty	`bool`	Whether to allocate a pseudo-terminal
rlimits	`list[Rlimit]`	POSIX resource limits

ExecOutput

Returned by exec() · shell() · ExecHandle.collect()

The result of a completed command execution: collected output plus exit status. All members are properties. In TTY mode, stdout_bytes contains the combined terminal output and stderr_bytes is empty because a PTY doesn’t preserve separate stdout and stderr streams.

Property	Type	Description
exit_code	`int`	Process exit code
success	`bool`	`True` when `exit_code == 0`
stdout_text	`str`	Collected stdout decoded as UTF-8. Raises on invalid encoding
stderr_text	`str`	Collected stderr decoded as UTF-8. Raises on invalid encoding
stdout_bytes	`bytes`	Raw stdout bytes
stderr_bytes	`bytes`	Raw stderr bytes

ExecEvent

Emitted by ExecHandle

Native event object emitted by recv() and by iterating an ExecHandle. Fields that don’t apply to a given event are None.

Property	Type	Description
event_type	`ExecEventType`	Exact event discriminator
pid	`int \| None`	Guest PID, set on `ExecEventType.STARTED`
data	`bytes \| None`	Output bytes on `STDOUT` / `STDERR`, or a UTF-8 failure message on `FAILED` / `STDIN_ERROR`
code	`int \| None`	Exit code on `EXITED`, or errno when available on `FAILED` / `STDIN_ERROR`

ExecEventType

Returned by ExecEvent.event_type

String enum (enum.StrEnum) identifying a streaming execution event.

Member	Value	Description
`ExecEventType.STARTED`	`"started"`	Process started; `pid` is populated
`ExecEventType.STDOUT`	`"stdout"`	Standard-output bytes are available in `data`
`ExecEventType.STDERR`	`"stderr"`	Standard-error bytes are available in `data`
`ExecEventType.EXITED`	`"exited"`	Process exited; `code` is populated
`ExecEventType.FAILED`	`"failed"`	Process startup failed
`ExecEventType.STDIN_ERROR`	`"stdin_error"`	Writing process stdin failed

ExitStatus

Used by ExecHandle.wait()

Frozen dataclass describing a process exit result. ExecHandle.wait() returns the same information as a (code, success) tuple.

Field	Type	Description
code	`int`	Process exit code
success	`bool`	`True` when `code == 0`

StdinMode

Used internally by Stdin

String enum (enum.StrEnum) identifying how command stdin is connected.

Member	Value	Description
`StdinMode.NULL`	`"null"`	Connect stdin to `/dev/null`
`StdinMode.PIPE`	`"pipe"`	Expose a writable `ExecSink`
`StdinMode.BYTES`	`"bytes"`	Send inline bytes, then EOF

RlimitResource

Used by Rlimit.resource

String enum (enum.StrEnum) naming a limitable POSIX resource.

Member	Value	Description
`RlimitResource.CPU`	`"cpu"`	CPU time
`RlimitResource.FSIZE`	`"fsize"`	File size
`RlimitResource.DATA`	`"data"`	Data segment size
`RlimitResource.STACK`	`"stack"`	Stack size
`RlimitResource.CORE`	`"core"`	Core file size
`RlimitResource.RSS`	`"rss"`	Resident set size
`RlimitResource.NPROC`	`"nproc"`	Number of processes
`RlimitResource.NOFILE`	`"nofile"`	Open file descriptors
`RlimitResource.MEMLOCK`	`"memlock"`	Locked memory
`RlimitResource.AS`	`"as"`	Virtual memory
`RlimitResource.LOCKS`	`"locks"`	File locks
`RlimitResource.SIGPENDING`	`"sigpending"`	Pending signals
`RlimitResource.MSGQUEUE`	`"msgqueue"`	Message queue size
`RlimitResource.NICE`	`"nice"`	Nice priority ceiling
`RlimitResource.RTPRIO`	`"rtprio"`	Real-time priority ceiling
`RlimitResource.RTTIME`	`"rttime"`	Real-time CPU time

​Sandbox

​sandbox.exec()

​sandbox.shell()

​sandbox.exec_stream()

​sandbox.shell_stream()

​sandbox.attach()

​sandbox.attach_shell()

​ExecHandle

​handle.id

​handle.take_stdin()

​handle.recv()

​handle.wait()

​handle.collect()

​handle.signal()

​handle.kill()

​handle.resize()

​ExecSink

​sink.write()

​sink.close()

​Stdin

​Stdin.null()

​Stdin.pipe()

​Stdin.bytes()

​Rlimit

​Rlimit.nofile()

​Rlimit.cpu()

​Rlimit.as_()

​Rlimit.nproc()

​Rlimit.fsize()

​Rlimit.memlock()

​Rlimit.stack()

​Types

​ExecOptions

​ExecOutput

​ExecEvent

​ExecEventType

​ExitStatus

​StdinMode

​RlimitResource

Sandbox

sandbox.exec()

sandbox.shell()

sandbox.exec_stream()

sandbox.shell_stream()

sandbox.attach()

sandbox.attach_shell()

ExecHandle

handle.id

handle.take_stdin()

handle.recv()

handle.wait()

handle.collect()

handle.signal()

handle.kill()

handle.resize()

ExecSink

sink.write()

sink.close()

Stdin

Stdin.null()

Stdin.pipe()

Stdin.bytes()

Rlimit

Rlimit.nofile()

Rlimit.cpu()

Rlimit.as_()

Rlimit.nproc()

Rlimit.fsize()

Rlimit.memlock()

Rlimit.stack()

Types

ExecOptions

ExecOutput

ExecEvent

ExecEventType

ExitStatus

StdinMode

RlimitResource