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)

Click the + button on the home page. Choose a shell or enter a custom command.

List sessions

relay list

The home page (/) shows all active sessions with their status and last activity.

Attach to a session

relay attach <session-id>

Press Ctrl+] to detach without killing the session.

Click any session in the list to open it in the terminal view.

Stop a session

relay stop <session-id>

Open the session info panel and tap Stop.

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.