Skip to main content
A PTY (pseudo-terminal) is a virtual terminal interface that lets programs interact with a shell as if connected to a real terminal. The sandbox.pty module creates interactive terminal sessions that run commands, accept input, and can be resized while running. This fits REPLs and debuggers, interactive command line tools that prompt for input, and long-running processes that need monitoring.
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.
A PTY is identified by its process ID (pid), returned from create(). Pass that pid to send input, resize, connect, and kill. Output is delivered to a callback as raw bytes.

Use a PTY

1

Create a PTY

Create a PTY and receive its output through a callback. The call returns a handle whose pid identifies the PTY.
2

Send input

Send input to a running PTY by its pid. The data is raw bytes.
3

Resize the terminal

Call resize when the terminal window changes size.
4

Reconnect to the PTY

Connect to a PTY that is already running by its pid. Running processes are listed by sandbox.commands.list(). The returned handle receives further output from the PTY.
5

Kill the PTY

kill terminates the PTY with SIGKILL. It returns true if the PTY was killed, or false if no PTY with that pid was found.

Full example

PTY options

PtySize
Terminal dimensions. Pass cols and rows as keyword arguments.
string
User to run the PTY as. Optional.
string
Working directory. Optional.
dict
Environment variables. TERM, LANG and LC_ALL are defaulted. Optional.
number
default:"60"
PTY timeout, in seconds.
In Python, output is delivered through wait(on_pty=...) instead of an onData option.

Interactive example

Create a PTY, send an interactive command that prompts for input, then wait for it to finish and read the exit code. In Python, wait(on_pty=...) streams output to the callback and returns the result.
Last modified on November 19, 2026