Interactive PTY Terminal via WebSocket

The PTY endpoint gives you a full interactive terminal inside a capsule. Unlike the exec and stream endpoints, PTY sessions allocate a pseudo-terminal device — the same infrastructure that powers SSH and terminal emulators. This means programs that rely on a TTY (interactive shells, editors like vim, full-screen CLI apps) behave correctly. Sessions persist across WebSocket disconnections. If your connection drops, the process keeps running inside the capsule and you can reconnect using the session tag.

Endpoint

GET https://app.wrenn.dev/api/v1/capsules/{id}/pty

Upgrade this request to a WebSocket by including the standard Upgrade: websocket headers.

Authentication

string

required

Your team’s API key.

Path parameters

string

required

The capsule ID.

WebSocket protocol

Client messages — starting a session

Send this as the first message to start a new PTY session:

{
  "type": "start",
  "cmd": "/bin/bash",
  "args": [],
  "cols": 80,
  "rows": 24,
  "envs": {"TERM": "xterm-256color"},
  "cwd": "/home/user",
  "user": "user"
}

Field	Type	Required	Default	Description
`type`	string	Yes	—	Must be `"start"`.
`cmd`	string	No	`"/bin/bash"`	Command to run as the terminal process.
`args`	string[]	No	`[]`	Arguments to pass to the command.
`cols`	integer	No	`80`	Terminal width in columns.
`rows`	integer	No	`24`	Terminal height in rows.
`envs`	object	No	`{}`	Additional environment variables.
`cwd`	string	No	—	Working directory for the process.
`user`	string	No	—	User to run the process as.

Client messages — reconnecting

To reconnect to an existing PTY session, send the tag you received in the started server message:

{
  "type": "connect",
  "tag": "pty-abc123de"
}

Client messages — during a session

Once the session is established (after receiving started from the server), you can send: Input — keystrokes or pasted text, base64-encoded:

{
  "type": "input",
  "data": "<base64-encoded bytes>"
}

Resize — when the terminal window changes size:

{
  "type": "resize",
  "cols": 120,
  "rows": 40
}

Kill — terminate the terminal process:

{
  "type": "kill"
}

Server messages

`type`	Fields	When sent
`started`	`tag: string`, `pid: integer`	Session started. Save `tag` to reconnect later.
`output`	`data: string`	Terminal output, base64-encoded. Decode before rendering.
`exit`	`exit_code: integer`	Terminal process exited.
`error`	`data: string`, `fatal: boolean`	An error occurred. When `fatal` is `true`, the connection closes.
`ping`	—	Keepalive from the server; no response required.

{"type": "started", "tag": "pty-abc123de", "pid": 42}
{"type": "output", "data": "YmFzaC01LjIkIA=="}
{"type": "exit", "exit_code": 0}

All PTY data — both input you send and output you receive — is base64-encoded. Raw terminal bytes include ANSI escape sequences and control codes that are not valid UTF-8. Decode the data field before passing it to your terminal renderer.

PTY sessions survive WebSocket disconnections. The process keeps running in the capsule. Save the tag from the started message and use {"type": "connect", "tag": "..."} to rejoin a session after a disconnect.

Python SDK

The SDK wraps the WebSocket protocol and decodes base64 output automatically. Iterate over the session directly to receive events.

import sys
from wrenn import Capsule

with Capsule(wait=True) as capsule:
    with capsule.pty(cmd="/bin/bash", cols=120, rows=40) as term:
        # Send input as raw bytes
        term.write(b"ls -la\n")

        # Iterate events
        for event in term:
            if event.type == "output":
                sys.stdout.buffer.write(event.data)
            elif event.type == "exit":
                break

# Reconnect to an existing session using its tag
saved_tag = term.tag
with capsule.pty_connect(saved_tag) as term:
    term.write(b"echo reconnected\n")
    for event in term:
        if event.type == "output":
            sys.stdout.buffer.write(event.data)
        elif event.type == "exit":
            break

Errors

Status	Meaning
`404`	Capsule not found or does not belong to your team.
`409`	Capsule is not in the `running` state. Start or resume the capsule first.

Capsules

Execution

Files

Snapshots

Interactive PTY Terminal via WebSocket

Endpoint

Authentication

Path parameters

WebSocket protocol

Client messages — starting a session

Client messages — reconnecting

Client messages — during a session

Server messages

Python SDK

Errors

​Endpoint

​Authentication

​Path parameters

​WebSocket protocol

​Client messages — starting a session

​Client messages — reconnecting

​Client messages — during a session

​Server messages

​Python SDK

​Errors

Endpoint

Authentication

Path parameters

WebSocket protocol

Client messages — starting a session

Client messages — reconnecting

Client messages — during a session

Server messages

Python SDK

Errors