Skip to main content
commands.run() runs terminal commands inside a sandbox. It returns the command output, can start a process in the background, and can stream output through callbacks as the process produces it.
Install the SDK, or the CLI for ppio commands, and set the PPIO_API_KEY and PPIO_DOMAIN environment variables before running these examples. See Quickstart and Install and authenticate.

Run a command

Call commands.run() with a command string. The returned result contains the command output. In the CLI examples, <sandbox-id> is the sandbox ID.

Read the command output

Use stdout to read what the command printed.

Run a command in the background

Pass the background option to start a long-running process, such as a server, without blocking on it.

Override environment variables for one command

Override or append environment variables for a single command with the envs option. It applies only to that command.

Stream output as it is produced

For long-running commands, pass on_stdout / on_stderr in Python or onStdout / onStderr in Node.js to receive output as it is produced, instead of waiting for the command to finish. Each callback receives its output as soon as it exists, with stdout and stderr delivered separately. The returned result still contains the final exit code.
Keep callbacks lightweight. Long blocking work inside a callback holds up event processing and can disconnect the underlying connection. Buffer the data, or hand it to another task or thread, when heavy processing is needed.

Stream a background command

To keep the program running while a command streams, start it with background=True in Python or background: true in Node.js. The call returns a CommandHandle instead of waiting for the result. The same callbacks can be attached, other work can continue, and wait() blocks until the command finishes and returns its CommandResult.

Retrieve the full output

When real-time output is not needed, run the command in the foreground and read the full stdout and stderr from the returned CommandResult. This is the simplest approach for commands with a predictable, short duration.

Output of a background command

For a command started in the background, the accumulated output is also available on the handle after it completes.

Command options

string
Command to execute.
bool
default:"False"
True returns a command handle and does not wait for the command to finish.
dict
Environment variables for this command only.
callable
Callback for stdout output as it is produced.
callable
Callback for stderr output as it is produced.

Result fields

str
Full standard output collected from the command.
str
Full standard error collected from the command.
int
Command exit code. 0 indicates success.
str
Error message when the command failed; otherwise empty.
A command that exits with a non-zero code raises an error. The Errors page lists it, and the error carries the same stdout, stderr, exitCode and error fields, so the output is still readable after a failure.
Last modified on November 19, 2026