Session Management

How to create, list, attach, detach, and stop terminal sessions.

Create a session

relay bash                    # interactive shell
relay htop                    # run a specific command
relay --detach bash           # create without attaching (print URL)

List sessions

relay list

Attach to a session

relay attach <session-id>

Press Ctrl+] to detach without killing the session.

Stop a session

relay stop <session-id>

Stopping a session kills the underlying process. This is not reversible.

Watch for an agent that needs you

pty-host tracks an agentState per session (working, blocked, done, idle, unknown) for recognized coding agents such as Claude Code, Codex, and opencode. It shows as a chip in the web sidebar and as a column in the TUI picker, both of which sort blocked sessions first, and it drives the "Agent blocked" push notification.

From a script:

relay wait a1b2c3d4 --state blocked --timeout 900 && say "agent needs you"
relay events | jq -c 'select(.event == "session.agent_state")'

Rename a session

relay rename a1b2c3d4 "api refactor"   # pinned: the shell's own title no longer replaces it
relay rename a1b2c3d4 --unpin

In the TUI, press , in the picker or Ctrl+B , while attached.

Multiple viewers

Multiple clients (CLI and browser) can connect to the same session simultaneously. Everyone sees the same output in real-time, and any connected client can type.