The PTY sub-client is accessed via client.pty on a SandboxClient instance.

Attached sessions communicate over WebSocket: binary frames are raw PTY output, text frames are JSON control events.

create

pty.create(command=None, env=None, workdir=None, cols=80, rows=24, tag=None)

Creates a new PTY session.

• Example:

pty = client.pty.create(command=["sh"], cols=80, rows=24)
print(pty.pty_id, pty.state)

• Args:

  • command: List[str], optional, the command to run in the PTY,
    • default: the server's default shell.
  • env: Dict[str, str], optional, environment variables to set.
  • workdir: str, optional, working directory for the session.
  • cols: int, optional, terminal columns, default: 80.
  • rows: int, optional, terminal rows, default: 24.
  • tag: str, optional, a label to filter sessions in list.

• Returns: V1Pty, with pty_id, pid, state, attached, cols, rows, tag, and activity timestamps.

list

pty.list(tag=None)

Lists PTY sessions.

• Args:

  • tag: str, optional, only return sessions created with this tag.

• Returns: V1PtyList, with sessions, a list of V1Pty.

get

pty.get(id)

Fetches a PTY session by id.

• Args:

  • id: str, the PTY session id.

• Returns: V1Pty

delete

pty.delete(id)

Terminates and deletes a PTY session.

• Args:
  • id: str, the PTY session id.

resize

pty.resize(id, cols, rows)

Resizes a PTY session's terminal.

• Args:
  • id: str, the PTY session id.
  • cols: int, terminal columns.
  • rows: int, terminal rows.

signal

pty.signal(id, signal)

Sends a signal to a PTY session's process.

• Args:
  • id: str, the PTY session id.
  • signal: str, the signal name, e.g. SIGTERM or SIGKILL.

attach

pty.attach(id, replay_bytes=None, timeout=None)

Attaches to a PTY session over WebSocket.

The initial attached control event is consumed before this method returns; a bad initial frame closes the socket and raises.

The returned client is a context manager and exposes:

• send_stdin(data): sends bytes to the PTY's stdin.
• recv(): receives the next frame, bytes for raw PTY output, dicts for JSON control events.
• resize(cols, rows): resizes the terminal.
• signal(signal) / kill(signal="SIGTERM"): signals the process.
• attached_event: the initial attached control event.
• close(): closes the WebSocket.

• Example:

pty = client.pty.create(command=["sh"])
with client.pty.attach(pty.pty_id, replay_bytes=1024) as ws:
    ws.send_stdin(b"echo ready\n")
    frame = ws.recv()

• Args:

  • id: str, the PTY session id.
  • replay_bytes: int, optional, bytes of recent output to replay on attach.
  • timeout: int, optional, connection timeout in seconds.

• Returns: SandboxPtyWSClient, a connected PTY WebSocket client.

• Raises:

  • PolyaxonClientException: If the attach handshake fails.