Skip to main content
GET
The live terminal (WebSocket).

Authorizations

Authorization
string
header
required

The token from api.json on the loopback listener; the remote token from remote.json (rakumux remote token) on the remote listener.

Headers

X-Rakumux-Session-Id
string

Act as this session (with X-Rakumux-Session-Token).

X-Rakumux-Session-Token
string

The session's RAKUMUX_SESSION_TOKEN.

X-Rakumux-Agent
string

Act for the session that bound this agent's conversation (with X-Rakumux-Agent-Conversation), e.g. opencode. Not with the session headers.

Pattern: ^[a-z0-9_-]{1,32}$
X-Rakumux-Agent-Conversation
string

The agent's conversation id, e.g. OpenCode's ses_….

Path Parameters

id
string
required

Opaque session id (letters, digits, -, _). Never derive anything from it.

Pattern: ^[A-Za-z0-9_-]{1,128}$

Query Parameters

role
enum<string>
default:observer

controller takes input and sets the terminal size (the previous controller becomes an observer).

Available options:
observer,
controller
cols
integer

The client's terminal width. Required for controllers.

Required range: 1 <= x <= 1000
rows
integer

The client's terminal height. Required for controllers.

Required range: 1 <= x <= 1000

Response

Switching to the WebSocket protocol; messages are AttachMessage (text, server → client), output bytes (binary, server → client), input bytes (binary, client → server) and AttachCommand (text, client → server).

A text message of GET /v1/sessions/{id}/attach (server → client). Terminal output travels in binary frames.

type
enum<string>
required

attached (first, once): session, role, cols, rows, checkpoint, offset. resized: cols, rows, checkpoint, offset: reset the terminal to the checkpoint. role_changed: role. title: title. bell. exited: code; the socket closes next. lagged: output was dropped because the client fell behind; attach again.

Available options:
attached,
resized,
role_changed,
title,
bell,
exited,
lagged
session
object
role
enum<string>
Available options:
observer,
controller
cols
integer
rows
integer
checkpoint
string

Base64 of bytes that bring a fresh terminal of cols×rows to the current screen.

offset
integer

Output offset the checkpoint corresponds to.

title
string
code
integer | null

Exit code; null when unknown.