💻 Pty API Reference
April 16, 2026 · View on GitHub
Overview
The PTY module provides interactive terminal sessions in cloud sandbox environments. Unlike the Command module which executes single commands, PTY gives you a persistent, interactive shell with real-time streaming output, terminal resize support, and session lifecycle management.
📚 Tutorial
Learn how to use interactive terminal sessions in cloud environments
Pty
PTY module entry point – accessed as session.getPty().
Constructor
public Pty(Session session)
Methods
create
public PtyHandle create(int cols, int rows, String cwd, Map<String, String> envs, String shell, Consumer<byte[]> onData, long timeoutMs) throws Exception
public PtyHandle create() throws Exception
public PtyHandle create(int cols, int rows, Consumer<byte[]> onData) throws Exception
Create a new PTY session.
Parameters:
cols(int): Terminal columns (default 80)rows(int): Terminal rows (default 24)cwd(String): Working directory (null for default)envs(Map<String,String>): Extra environment variables (null for default)shell(String): Shell program (null for default)onData(Consumer<byte[]>): Callback for output data (may be null)timeoutMs(long): Timeout in milliseconds (0 defaults to 30 000)
Returns:
PtyHandle: A PtyHandle connected to the new session
Throws:
PtyException: if the terminal size is invalidException: on communication failure
list
public List<PtySession> list() throws Exception
List all active PTY sessions.
connect
public PtyHandle connect(String ptySessionId, Consumer<byte[]> onData) throws Exception
Reconnect to an existing PTY session.
kill
public void kill(String ptySessionId) throws Exception
Kill a PTY session by ID.
PtyHandle
An active connection to a PTY session.
Methods
getPtySessionId
public String getPtySessionId()
isConnected
public boolean isConnected()
getExitCode
public Integer getExitCode()
sendInput
public void sendInput(byte[] data) throws PtyNotConnectedException
Send input bytes to the PTY.
resize
public void resize(int cols, int rows) throws PtyNotConnectedException, PtyException
Resize the terminal.
kill
public void kill() throws Exception
Kill the PTY process.
wait
public int wait(int timeoutMs) throws PtyException
Wait for the PTY process to exit and return its exit code.
Parameters:
timeoutMs(int): Timeout in milliseconds (0 for no timeout)
Returns:
int: The exit code of the PTY process
Throws:
PtyException: on error or timeout
disconnect
public void disconnect()
Disconnect from the PTY (process continues on server).
PtySession
Read-only snapshot of a PTY session.
Constructor
public PtySession(String ptySessionId, int cols, int rows, String status, Integer exitCode)
Methods
getPtySessionId
public String getPtySessionId()
getCols
public int getCols()
getRows
public int getRows()
getExitCode
public Integer getExitCode()
💡 Best Practices
- Always disconnect or wait when done with a PTY handle
- Use carriage return (\r) to submit commands instead of newline
- Handle the on_data callback efficiently as it may be called frequently
- Set terminal size to match the client for correct line wrapping
- Use appropriate timeouts with wait() to avoid blocking indefinitely