A WebSocket. Server → client: first a text attached message
(AttachMessage) with a base64 checkpoint: fed to a fresh terminal of
cols×rows it shows the current screen. Then binary frames carry the
terminal output, in order from offset, and text messages the events
resized (reset the terminal to its checkpoint), role_changed,
title, bell, exited and lagged (output was dropped: attach
again). The server closes the socket when the stream ends (exit,
delete, daemon gone).
Client → server: binary frames are input bytes (a controller’s; an
observer’s are ignored); text messages are AttachCommands (resize,
promote, demote, fit). Closing the socket detaches.
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.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Rakumux","description":"Terminal sessions for coding agents, in one fast terminal UI.","colors":{"primary":"#d9692a","light":"#ff9e64","dark":"#c85a1c"},"logo":{"light":"https://mintcdn.com/human-unsupervised-pty-ltd/mZ98KnFkRMJsaXOd/logo/light.svg?fit=max\u0026auto=format\u0026n=mZ98KnFkRMJsaXOd\u0026q=85\u0026s=16a9ca71ea1e16b851ab93e3d34b5ea7","dark":"https://mintcdn.com/human-unsupervised-pty-ltd/mZ98KnFkRMJsaXOd/logo/dark.svg?fit=max\u0026auto=format\u0026n=mZ98KnFkRMJsaXOd\u0026q=85\u0026s=b9eef03a9ddf9ac932d19bff61c5d469","href":"https://rakumux.com"},"favicon":"https://mintcdn.com/human-unsupervised-pty-ltd/mZ98KnFkRMJsaXOd/favicon.svg?fit=max\u0026auto=format\u0026n=mZ98KnFkRMJsaXOd\u0026q=85\u0026s=6aa6bca8a6274d330984efae6158d64c","api":{"playground":{"display":"simple"}},"appearance":{"default":"dark"},"background":{"color":{"light":"#ffffff","dark":"#101119"}},"navbar":{"links":[{"href":"https://rakumux.com","label":"rakumux.com"},{"href":"https://github.com/humanunsupervised/rakumux/releases","label":"Releases"}],"primary":{"type":"github","href":"https://github.com/humanunsupervised/rakumux"}},"footer":{"socials":{"github":"https://github.com/humanunsupervised/rakumux","website":"https://rakumux.com"}},"fonts":{"family":"Geist"},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"human-unsupervised-pty-ltd","hasAudioNarration":false,"actualSubdomain":"human-unsupervised-pty-ltd","customDomains":["rakumux.com"],"gitSource":{"type":"github","owner":"humanunsupervised","repo":"rakumux-cloud","deployBranch":"main","contentDirectory":"docs","isPrivate":true,"mountPath":"","label":"","_id":"6ade9d72ae0dc487a6155e47"},"chroma":{"latestBuiltDeploymentHistoryId":"6ae26b05b8121111e5b87ec8","collectionId":"4e0469bb-aed2-43b2-b770-b15bba515194","liveDeploymentHistoryId":"6ae26b05b8121111e5b87ec8","schemaVersion":"v3"},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6ae33189217e82a3b924924c","clientVersion":"0.0.4006","searchFilterCounts":[{"language":"default","tag":"Guides","count":31},{"language":"default","tag":"API reference","count":14},{"language":"default","tag":"Endpoints","count":13},{"language":"default","tag":"Using Rakumux","count":8},{"language":"default","tag":"sessions","count":8},{"language":"default","tag":"Get started","count":5},{"language":"default","tag":"Coding agents","count":4},{"language":"default","tag":"Where to run it","count":4},{"language":"default","tag":"Account and AI titles","count":3},{"language":"default","tag":"Reference","count":3}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"/docs","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"pause-universal-search-reconcile","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"per-site-search-delta","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-private-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[],"page":{"pagePath":"api-reference/streams/the-live-terminal-websocket","slug":"/api-reference/streams/the-live-terminal-websocket","pageMetadata":{"title":"The live terminal (WebSocket).","description":"A WebSocket. Server → client: first a text `attached` message\n(`AttachMessage`) with a base64 `checkpoint`: fed to a fresh terminal of\n`cols`×`rows` it shows the current screen. Then binary frames carry the\nterminal output, in order from `offset`, and text messages the events\n`resized` (reset the terminal to its checkpoint), `role_changed`,\n`title`, `bell`, `exited` and `lagged` (output was dropped: attach\nagain). The server closes the socket when the stream ends (exit,\ndelete, daemon gone).\n\nClient → server: binary frames are input bytes (a controller's; an\nobserver's are ignored); text messages are `AttachCommand`s (`resize`,\n`promote`, `demote`, `fit`). Closing the socket detaches.\n\nSession callers can't attach (403).\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/sessions/{id}/attach","href":"/api-reference/streams/the-live-terminal-websocket","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"A WebSocket. Server → client: first a text \", _jsx(_components.code, {\n children: \"attached\"\n }), \" message\\n(\", _jsx(_components.code, {\n children: \"AttachMessage\"\n }), \") with a base64 \", _jsx(_components.code, {\n children: \"checkpoint\"\n }), \": fed to a fresh terminal of\\n\", _jsx(_components.code, {\n children: \"cols\"\n }), \"×\", _jsx(_components.code, {\n children: \"rows\"\n }), \" it shows the current screen. Then binary frames carry the\\nterminal output, in order from \", _jsx(_components.code, {\n children: \"offset\"\n }), \", and text messages the events\\n\", _jsx(_components.code, {\n children: \"resized\"\n }), \" (reset the terminal to its checkpoint), \", _jsx(_components.code, {\n children: \"role_changed\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"title\"\n }), \", \", _jsx(_components.code, {\n children: \"bell\"\n }), \", \", _jsx(_components.code, {\n children: \"exited\"\n }), \" and \", _jsx(_components.code, {\n children: \"lagged\"\n }), \" (output was dropped: attach\\nagain). The server closes the socket when the stream ends (exit,\\ndelete, daemon gone).\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Client → server: binary frames are input bytes (a controller’s; an\\nobserver’s are ignored); text messages are \", _jsx(_components.code, {\n children: \"AttachCommand\"\n }), \"s (\", _jsx(_components.code, {\n children: \"resize\"\n }), \",\\n\", _jsx(_components.code, {\n children: \"promote\"\n }), \", \", _jsx(_components.code, {\n children: \"demote\"\n }), \", \", _jsx(_components.code, {\n children: \"fit\"\n }), \"). Closing the socket detaches.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Session callers can’t attach (403).\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"The live terminal (WebSocket).","description":"A WebSocket. Server → client: first a text `attached` message\n(`AttachMessage`) with a base64 `checkpoint`: fed to a fresh terminal of\n`cols`×`rows` it shows the current screen. Then binary frames carry the\nterminal output, in order from `offset`, and text messages the events\n`resized` (reset the terminal to its checkpoint), `role_changed`,\n`title`, `bell`, `exited` and `lagged` (output was dropped: attach\nagain). The server closes the socket when the stream ends (exit,\ndelete, daemon gone).\n\nClient → server: binary frames are input bytes (a controller's; an\nobserver's are ignored); text messages are `AttachCommand`s (`resize`,\n`promote`, `demote`, `fit`). Closing the socket detaches.\n\nSession callers can't attach (403).\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/sessions/{id}/attach","href":"/api-reference/streams/the-live-terminal-websocket","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["streams"],"operationId":"attachSession","summary":"The live terminal (WebSocket).","description":"A WebSocket. Server → client: first a text `attached` message\n(`AttachMessage`) with a base64 `checkpoint`: fed to a fresh terminal of\n`cols`×`rows` it shows the current screen. Then binary frames carry the\nterminal output, in order from `offset`, and text messages the events\n`resized` (reset the terminal to its checkpoint), `role_changed`,\n`title`, `bell`, `exited` and `lagged` (output was dropped: attach\nagain). The server closes the socket when the stream ends (exit,\ndelete, daemon gone).\n\nClient → server: binary frames are input bytes (a controller's; an\nobserver's are ignored); text messages are `AttachCommand`s (`resize`,\n`promote`, `demote`, `fit`). Closing the socket detaches.\n\nSession callers can't attach (403).\n","parameters":["5e665227-d973-426d-952d-a30e7730631f","337559ae-c775-41d5-b74d-d84389db4c5f","0512e9b9-7fef-4a9c-a5bc-2bca0c167c24"],"responses":{"101":"00b3fe92-f726-41c7-a4fe-5c4a7a735ec7","400":"2a02f6d2-56cd-4d1a-b9ff-f495d27228eb","401":"12e0085c-f7d9-4d93-aa64-2fc467022628","403":"d474475a-829e-4311-b01e-ff29eac2f863","404":"417f2fae-5a26-4067-a17d-b79f4c918749","409":"1e97353b-51a3-4b2b-9dac-941589993d2c","426":"6d550cdb-a2c8-4bc8-9d92-750830e93c7b","503":"8782003e-5881-452c-b194-e6827f4aec30"},"method":"get","type":"path","servers":["148d6ec4-37ee-4b39-b183-0076f7538d6b","e1fd317f-ae47-43b7-b2f2-7b73b44b04bb"],"security":["46fbe4c6-7054-4f0f-be85-84b70d4f83dd"],"path":"/v1/sessions/{id}/attach","baseUrlOptions":["http://127.0.0.1:{port}","http://{host}:{port}"],"title":"The live terminal (WebSocket).","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"5e665227-d973-426d-952d-a30e7730631f":{"name":"role","in":"query","description":"`controller` takes input and sets the terminal size (the previous controller becomes an observer).","schema":{"type":"string","enum":["observer","controller"],"default":"observer","description":"`controller` takes input and sets the terminal size (the previous controller becomes an observer).","uniqueKey":"","typeLabel":"enum\u003cstring>"}},"337559ae-c775-41d5-b74d-d84389db4c5f":{"name":"cols","in":"query","description":"The client's terminal width. Required for controllers.","schema":{"type":"integer","minimum":1,"maximum":1000,"description":"The client's terminal width. Required for controllers.","uniqueKey":"","typeLabel":"integer"}},"0512e9b9-7fef-4a9c-a5bc-2bca0c167c24":{"name":"rows","in":"query","description":"The client's terminal height. Required for controllers.","schema":{"type":"integer","minimum":1,"maximum":1000,"description":"The client's terminal height. Required for controllers.","uniqueKey":"","typeLabel":"integer"}},"9ad3e915-32b6-41d3-ab5c-a52f5cd45dfa":{"name":"id","in":"path","required":true,"description":"Opaque session id (letters, digits, `-`, `_`). Never derive anything from it.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,128}$","isRequired":true,"description":"Opaque session id (letters, digits, `-`, `_`). Never derive anything from it.","uniqueKey":"","typeLabel":"string"}},"72b6bfde-fdac-489a-bd85-5db34c338820":{"name":"X-Rakumux-Session-Id","in":"header","required":false,"description":"Act as this session (with X-Rakumux-Session-Token).","schema":{"type":"string","isRequired":false,"description":"Act as this session (with X-Rakumux-Session-Token).","uniqueKey":"","typeLabel":"string"}},"68d5b6f6-b994-4a8b-872a-722584e16419":{"name":"X-Rakumux-Session-Token","in":"header","required":false,"description":"The session's RAKUMUX_SESSION_TOKEN.","schema":{"type":"string","isRequired":false,"description":"The session's RAKUMUX_SESSION_TOKEN.","uniqueKey":"","typeLabel":"string"}},"73f348b2-538f-4635-a16d-53e17ec80b00":{"name":"X-Rakumux-Agent","in":"header","required":false,"description":"Act for the session that bound this agent's conversation (with X-Rakumux-Agent-Conversation), e.g. `opencode`. Not with the session headers.\n","schema":{"type":"string","pattern":"^[a-z0-9_-]{1,32}$","isRequired":false,"description":"Act for the session that bound this agent's conversation (with X-Rakumux-Agent-Conversation), e.g. `opencode`. Not with the session headers.\n","uniqueKey":"","typeLabel":"string"}},"a617c431-e519-433c-af3e-ba2676586b54":{"name":"X-Rakumux-Agent-Conversation","in":"header","required":false,"description":"The agent's conversation id, e.g. OpenCode's `ses_…`.","schema":{"type":"string","isRequired":false,"description":"The agent's conversation id, e.g. OpenCode's `ses_…`.","uniqueKey":"","typeLabel":"string"}}},"responses":{"00b3fe92-f726-41c7-a4fe-5c4a7a735ec7":{"description":"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).\n","content":{"application/json":{"schema":{"description":"A text message of `GET /v1/sessions/{id}/attach` (server → client). Terminal output travels in binary frames.\n","type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["attached","resized","role_changed","title","bell","exited","lagged"],"description":"`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.\n","isRequired":true,"uniqueKey":"type","typeLabel":"enum\u003cstring>"},"session":{"type":"object","required":["id","name","folder","cwd","status","lifecycle","created_by","created_at","last_active_at"],"properties":{"id":{"type":"string","description":"Opaque id.","isRequired":true,"uniqueKey":"session.id","typeLabel":"string"},"name":{"type":"string","description":"Unique within the folder.","isRequired":true,"uniqueKey":"session.name","typeLabel":"string"},"folder":{"type":"string","description":"The folder (directory) the session was started in.","isRequired":true,"uniqueKey":"session.folder","typeLabel":"string"},"cwd":{"type":"string","description":"Current working directory (absolute).","isRequired":true,"uniqueKey":"session.cwd","typeLabel":"string"},"status":{"type":"string","enum":["live","exited","dead","unknown"],"description":"`live`: terminal running. `exited`: process ended, final screen kept. `dead`: record without terminal (after a crash, a reboot or `rakumux daemon stop`).\n","isRequired":true,"uniqueKey":"session.status","typeLabel":"enum\u003cstring>"},"lifecycle":{"type":"string","enum":["working","blocked","done","idle","unknown","none"],"description":"What the program (usually a coding agent) is doing; `none` = no agent.","isRequired":true,"uniqueKey":"session.lifecycle","typeLabel":"enum\u003cstring>"},"created_by":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["user","session"],"isRequired":true,"uniqueKey":"session.created_by.kind","typeLabel":"enum\u003cstring>"},"id":{"type":"string","description":"The creating session (kind `session`).","uniqueKey":"session.created_by.id","typeLabel":"string"}},"isRequired":true,"uniqueKey":"session.created_by","typeLabel":"object"},"created_at":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"session.created_at","typeLabel":"string\u003cdate-time>"},"last_active_at":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"session.last_active_at","typeLabel":"string\u003cdate-time>"},"project":{"type":"string","deprecated":true,"description":"Deprecated alias of `folder` (the same path).","uniqueKey":"session.project","typeLabel":"string"},"exit_code":{"type":"integer","uniqueKey":"session.exit_code","typeLabel":"integer"},"agent":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","examples":["claude","codex","opencode","pi"],"isRequired":true,"uniqueKey":"session.agent.kind","typeLabel":"string"},"session_id":{"type":"string","description":"The agent's own conversation id.","uniqueKey":"session.agent.session_id","typeLabel":"string"}},"uniqueKey":"session.agent","typeLabel":"object"},"reported":{"type":"object","description":"What the session reported about itself. Written by its own program; untrusted.","required":["at"],"properties":{"at":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"session.reported.at","typeLabel":"string\u003cdate-time>"},"state":{"type":"string","enum":["working","blocked","done","idle"],"uniqueKey":"session.reported.state","typeLabel":"enum\u003cstring>"},"text":{"type":"string","uniqueKey":"session.reported.text","typeLabel":"string"},"summary":{"type":"string","uniqueKey":"session.reported.summary","typeLabel":"string"},"files":{"type":"array","items":{"type":"string","uniqueKey":"session.reported.files.items.[INDEX]","typeLabel":"string"},"uniqueKey":"session.reported.files","typeLabel":"string[]"}},"uniqueKey":"session.reported","typeLabel":"object"},"activity":{"type":"object","description":"Fresh agent-hook metadata; absent when unavailable, expired or not live. Subagents are agent-internal, not Rakumux children.","required":["phase","active_subagents","updated_at"],"properties":{"phase":{"type":"string","enum":["working","waiting_for_response","running_tool","needs_input","idle","done","unknown"],"isRequired":true,"uniqueKey":"session.activity.phase","typeLabel":"enum\u003cstring>"},"active_subagents":{"type":"integer","minimum":0,"maximum":64,"isRequired":true,"uniqueKey":"session.activity.active_subagents","typeLabel":"integer"},"updated_at":{"type":"string","format":"date-time","isRequired":true,"uniqueKey":"session.activity.updated_at","typeLabel":"string\u003cdate-time>"}},"uniqueKey":"session.activity","typeLabel":"object"},"parent_id":{"type":"string","uniqueKey":"session.parent_id","typeLabel":"string"},"depth":{"type":"integer","uniqueKey":"session.depth","typeLabel":"integer"},"children":{"type":"array","items":{"type":"string","uniqueKey":"session.children.items.[INDEX]","typeLabel":"string"},"uniqueKey":"session.children","typeLabel":"string[]"},"command":{"type":"array","items":{"type":"string","uniqueKey":"session.command.items.[INDEX]","typeLabel":"string"},"description":"argv the session runs; absent for the user's login shell.","uniqueKey":"session.command","typeLabel":"string[]"},"startup_commands":{"type":"array","items":{"type":"string","uniqueKey":"session.startup_commands.items.[INDEX]","typeLabel":"string"},"uniqueKey":"session.startup_commands","typeLabel":"string[]"},"resume_command":{"type":"array","items":{"type":"string","uniqueKey":"session.resume_command.items.[INDEX]","typeLabel":"string"},"uniqueKey":"session.resume_command","typeLabel":"string[]"},"pinned":{"type":"boolean","uniqueKey":"session.pinned","typeLabel":"boolean"},"git":{"type":"object","required":["repo_root"],"properties":{"repo_root":{"type":"string","isRequired":true,"uniqueKey":"session.git.repo_root","typeLabel":"string"},"branch":{"type":"string","uniqueKey":"session.git.branch","typeLabel":"string"},"detached_at":{"type":"string","description":"Short commit id when HEAD is detached.","uniqueKey":"session.git.detached_at","typeLabel":"string"},"worktree":{"type":"string","description":"Linked worktree name; absent in the main worktree.","uniqueKey":"session.git.worktree","typeLabel":"string"},"repo":{"type":"string","description":"The repository's name, for display: its `origin` remote's (the URL's last path component without `.git`), else its main working tree's folder name. Absent from older daemons.\n","uniqueKey":"session.git.repo","typeLabel":"string"}},"uniqueKey":"session.git","typeLabel":"object"},"description":{"type":"string","uniqueKey":"session.description","typeLabel":"string"},"notes":{"type":"string","uniqueKey":"session.notes","typeLabel":"string"},"labels":{"type":"object","additionalProperties":{"type":"string","uniqueKey":"session.labels.additionalProperties","typeLabel":"string"},"uniqueKey":"session.labels","typeLabel":"object"},"private":{"type":"boolean","uniqueKey":"session.private","typeLabel":"boolean"},"is_self":{"type":"boolean","description":"The caller (identity headers) is this session.","uniqueKey":"session.is_self","typeLabel":"boolean"},"auto_named":{"type":"boolean","description":"The name was generated by Rakumux.","uniqueKey":"session.auto_named","typeLabel":"boolean"},"terminal":{"type":"object","description":"Present while the session is live.","required":["cols","rows"],"properties":{"cols":{"type":"integer","isRequired":true,"uniqueKey":"session.terminal.cols","typeLabel":"integer"},"rows":{"type":"integer","isRequired":true,"uniqueKey":"session.terminal.rows","typeLabel":"integer"},"pid":{"type":"integer","uniqueKey":"session.terminal.pid","typeLabel":"integer"},"foreground_process":{"type":"string","uniqueKey":"session.terminal.foreground_process","typeLabel":"string"},"title":{"type":"string","uniqueKey":"session.terminal.title","typeLabel":"string"},"controlled":{"type":"boolean","description":"A client holds input control.","uniqueKey":"session.terminal.controlled","typeLabel":"boolean"},"alternate_screen":{"type":"boolean","uniqueKey":"session.terminal.alternate_screen","typeLabel":"boolean"}},"uniqueKey":"session.terminal","typeLabel":"object"}},"uniqueKey":"session","typeLabel":"object"},"role":{"type":"string","enum":["observer","controller"],"uniqueKey":"role","typeLabel":"enum\u003cstring>"},"cols":{"type":"integer","uniqueKey":"cols","typeLabel":"integer"},"rows":{"type":"integer","uniqueKey":"rows","typeLabel":"integer"},"checkpoint":{"type":"string","description":"Base64 of bytes that bring a fresh terminal of `cols`×`rows` to the current screen.\n","uniqueKey":"checkpoint","typeLabel":"string"},"offset":{"type":"integer","description":"Output offset the checkpoint corresponds to.","uniqueKey":"offset","typeLabel":"integer"},"title":{"type":"string","uniqueKey":"title","typeLabel":"string"},"code":{"oneOf":[{"type":"integer","description":"Exit code; null when unknown.","uniqueKey":"code.oneOf.0","typeLabel":"integer"},{"type":"null","description":"Exit code; null when unknown.","uniqueKey":"code.oneOf.1","typeLabel":"null"}],"uniqueKey":"code","typeLabel":"integer | null"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"type":"attached","session":{"id":"\u003cstring>","name":"\u003cstring>","folder":"\u003cstring>","cwd":"\u003cstring>","status":"live","lifecycle":"working","created_by":{"kind":"user","id":"\u003cstring>"},"created_at":"2023-11-07T05:31:56Z","last_active_at":"2023-11-07T05:31:56Z","project":"\u003cstring>","exit_code":123,"agent":{"kind":"claude","session_id":"\u003cstring>"},"reported":{"at":"2023-11-07T05:31:56Z","state":"working","text":"\u003cstring>","summary":"\u003cstring>","files":["\u003cstring>"]},"activity":{"phase":"working","active_subagents":32,"updated_at":"2023-11-07T05:31:56Z"},"parent_id":"\u003cstring>","depth":123,"children":["\u003cstring>"],"command":["\u003cstring>"],"startup_commands":["\u003cstring>"],"resume_command":["\u003cstring>"],"pinned":true,"git":{"repo_root":"\u003cstring>","branch":"\u003cstring>","detached_at":"\u003cstring>","worktree":"\u003cstring>","repo":"\u003cstring>"},"description":"\u003cstring>","notes":"\u003cstring>","labels":{},"private":true,"is_self":true,"auto_named":true,"terminal":{"cols":123,"rows":123,"pid":123,"foreground_process":"\u003cstring>","title":"\u003cstring>","controlled":true,"alternate_screen":true}},"role":"observer","cols":123,"rows":123,"checkpoint":"\u003cstring>","offset":123,"title":"\u003cstring>","code":123}}},"exampleType":"generated"}},"exampleType":"generated"},"2a02f6d2-56cd-4d1a-b9ff-f495d27228eb":{"description":"`invalid_argument`: bad parameters or body, or a half-sent identity.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["not_found","invalid_argument","unauthenticated","out_of_scope","unsupported"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"details":{"oneOf":[{}],"uniqueKey":"error.details","typeLabel":"any"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"not_found","message":"\u003cstring>","details":"\u003cunknown>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"12e0085c-f7d9-4d93-aa64-2fc467022628":{"description":"`unauthenticated`: missing or wrong API token, or a session identity the daemon rejects.","headers":{"WWW-Authenticate":{"schema":{"type":"string","const":"Bearer"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["not_found","invalid_argument","unauthenticated","out_of_scope","unsupported"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"details":{"oneOf":[{}],"uniqueKey":"error.details","typeLabel":"any"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"not_found","message":"\u003cstring>","details":"\u003cunknown>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"d474475a-829e-4311-b01e-ff29eac2f863":{"description":"`permission_denied` (non-loopback Host, browser request, or the daemon's policy) or `out_of_scope` (a session acting outside its folder).\n","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["not_found","invalid_argument","unauthenticated","out_of_scope","unsupported"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"details":{"oneOf":[{}],"uniqueKey":"error.details","typeLabel":"any"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"not_found","message":"\u003cstring>","details":"\u003cunknown>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"417f2fae-5a26-4067-a17d-b79f4c918749":{"description":"`not_found`: no such session, folder or route.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["not_found","invalid_argument","unauthenticated","out_of_scope","unsupported"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"details":{"oneOf":[{}],"uniqueKey":"error.details","typeLabel":"any"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"not_found","message":"\u003cstring>","details":"\u003cunknown>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"1e97353b-51a3-4b2b-9dac-941589993d2c":{"description":"`session_not_live`: the session has no running terminal (it is `exited` or `dead`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["not_found","invalid_argument","unauthenticated","out_of_scope","unsupported"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"details":{"oneOf":[{}],"uniqueKey":"error.details","typeLabel":"any"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"not_found","message":"\u003cstring>","details":"\u003cunknown>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"6d550cdb-a2c8-4bc8-9d92-750830e93c7b":{"description":"`upgrade_required`: the route is a WebSocket; send `Connection: Upgrade`, `Upgrade: websocket`, `Sec-WebSocket-Version: 13` and a `Sec-WebSocket-Key`.\n","headers":{"Sec-WebSocket-Version":{"schema":{"type":"string","const":"13"}}},"content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["not_found","invalid_argument","unauthenticated","out_of_scope","unsupported"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"details":{"oneOf":[{}],"uniqueKey":"error.details","typeLabel":"any"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"not_found","message":"\u003cstring>","details":"\u003cunknown>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"8782003e-5881-452c-b194-e6827f4aec30":{"description":"`daemon_unavailable`: the daemon is not running and could not be started.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["not_found","invalid_argument","unauthenticated","out_of_scope","unsupported"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"string"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"details":{"oneOf":[{}],"uniqueKey":"error.details","typeLabel":"any"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"not_found","message":"\u003cstring>","details":"\u003cunknown>"}}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"46fbe4c6-7054-4f0f-be85-84b70d4f83dd":{"bearer":{"type":"http","scheme":"bearer","description":"The `token` from api.json on the loopback listener; the remote token from remote.json (`rakumux remote token`) on the remote listener.\n","scopes":[],"schemeName":"bearer"}}},"servers":{"148d6ec4-37ee-4b39-b183-0076f7538d6b":{"url":"http://127.0.0.1:{port}","variables":{"port":{"default":"0","description":"The port in api.json."}}},"e1fd317f-ae47-43b7-b2f2-7b73b44b04bb":{"url":"http://{host}:{port}","description":"The remote listener (remote access on); see api.json `remote_urls`.","variables":{"host":{"default":"machine.tailnet.ts.net","description":"The machine's MagicDNS name or Tailscale address."},"port":{"default":"7337","description":"remote.json `port`."}}}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"The `token` from api.json on the loopback listener; the remote token from remote.json (`rakumux remote token`) on the remote listener.\n","scopes":[],"schemeName":"bearer"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"The `token` from api.json on the loopback listener; the remote token from remote.json (`rakumux remote token`) on the remote listener.\n","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearer","name":"Authorization"}],"title":"bearer"}]},"originalFileLocation":"api-reference/openapi.yaml"},"subdomain":"human-unsupervised-pty-ltd","siteName":"Rakumux","title":"The live terminal (WebSocket). - Rakumux","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-27T10:59:59.278Z","originalFileLocation":"api-reference/streams/the-live-terminal-websocket.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"A WebSocket. Server → client: first a text attached message (AttachMessage) with a base64 checkpoint: fed to a fresh terminal of cols×rows it shows the current screen. Then binary frames carry the terminal output, in order from offset, and text messages the events resized (reset the terminal to its checkpoint), role_changed, title, bell, exited and lagged (output was dropped: attach again). The server closes the socket when the stream ends (exit, delete, daemon gone). Client → server: binary frames are input bytes (a controller\u0026#x27;s; an observer\u0026#x27;s are ignored); text messages are AttachCommands (resize, promote, demote, fit). Closing the socket detaches. Session callers can\u0026#x27;t attach (403).\">\u003cmeta data-mint-head name=\"application-name\" content=\"Rakumux\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"The live terminal (WebSocket). - Rakumux\">\u003cmeta data-mint-head property=\"og:description\" content=\"A WebSocket. Server → client: first a text attached message (AttachMessage) with a base64 checkpoint: fed to a fresh terminal of cols×rows it shows the current screen. Then binary frames carry the terminal output, in order from offset, and text messages the events resized (reset the terminal to its checkpoint), role_changed, title, bell, exited and lagged (output was dropped: attach again). The server closes the socket when the stream ends (exit, delete, daemon gone). Client → server: binary frames are input bytes (a controller\u0026#x27;s; an observer\u0026#x27;s are ignored); text messages are AttachCommands (resize, promote, demote, fit). Closing the socket detaches. Session callers can\u0026#x27;t attach (403).\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Rakumux\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://rakumux.com/docs/api-reference/streams/the-live-terminal-websocket\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://human-unsupervised-pty-ltd.mintlify.app/_mintlify/api/og/v2?division=streams\u0026amp;title=The+live+terminal+%28WebSocket%29.\u0026amp;description=A+WebSocket.+Server+%E2%86%92+client%3A+first+a+text+%60attached%60+message%0A%28%60AttachMessage%60%29+with+a+base64+%60checkpoint%60%3A+fed+to+a+fresh+terminal+of%0A%60cols%60%C3%97%60rows%60+it+shows+th\u0026amp;theme=e19a71dbfbaba376e1df0768\u0026amp;signature=e13e64c2e3b4d9b3d7423088d1565f5f6c09c04dc3cf22e89235211086d71b4e\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"The live terminal (WebSocket). - Rakumux\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"A WebSocket. Server → client: first a text attached message (AttachMessage) with a base64 checkpoint: fed to a fresh terminal of cols×rows it shows the current screen. Then binary frames carry the terminal output, in order from offset, and text messages the events resized (reset the terminal to its checkpoint), role_changed, title, bell, exited and lagged (output was dropped: attach again). The server closes the socket when the stream ends (exit, delete, daemon gone). Client → server: binary frames are input bytes (a controller\u0026#x27;s; an observer\u0026#x27;s are ignored); text messages are AttachCommands (resize, promote, demote, fit). Closing the socket detaches. Session callers can\u0026#x27;t attach (403).\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://human-unsupervised-pty-ltd.mintlify.app/_mintlify/api/og/v2?division=streams\u0026amp;title=The+live+terminal+%28WebSocket%29.\u0026amp;description=A+WebSocket.+Server+%E2%86%92+client%3A+first+a+text+%60attached%60+message%0A%28%60AttachMessage%60%29+with+a+base64+%60checkpoint%60%3A+fed+to+a+fresh+terminal+of%0A%60cols%60%C3%97%60rows%60+it+shows+th\u0026amp;theme=e19a71dbfbaba376e1df0768\u0026amp;signature=e13e64c2e3b4d9b3d7423088d1565f5f6c09c04dc3cf22e89235211086d71b4e\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/docs/mintlify-assets/_mintlify/favicons/human-unsupervised-pty-ltd/T2YdgaTW8imvJoWH/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Rakumux\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#d9692a\">\u003clink data-mint-head rel=\"canonical\" href=\"https://rakumux.com/docs/api-reference/streams/the-live-terminal-websocket\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/docs/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/api-reference/streams/the-live-terminal-websocket.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://rakumux.com/#organization\",\"name\":\"Rakumux\",\"url\":\"https://rakumux.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/human-unsupervised-pty-ltd/mZ98KnFkRMJsaXOd/logo/light.svg?fit=max\u0026auto=format\u0026n=mZ98KnFkRMJsaXOd\u0026q=85\u0026s=16a9ca71ea1e16b851ab93e3d34b5ea7\"}},{\"@type\":\"WebSite\",\"@id\":\"https://rakumux.com/docs#website\",\"name\":\"Rakumux\",\"url\":\"https://rakumux.com/docs\",\"publisher\":{\"@id\":\"https://rakumux.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://rakumux.com/docs/api-reference/streams/the-live-terminal-websocket#webpage\",\"url\":\"https://rakumux.com/docs/api-reference/streams/the-live-terminal-websocket\",\"name\":\"The live terminal (WebSocket).\",\"description\":\"A WebSocket. Server → client: first a text attached message (AttachMessage) with a base64 checkpoint: fed to a fresh terminal of cols×rows it shows the current screen. Then binary frames carry the terminal output, in order from offset, and text messages the events resized (reset the terminal to its checkpoint), role_changed, title, bell, exited and lagged (output was dropped: attach again). The server closes the socket when the stream ends (exit, delete, daemon gone). Client → server: binary frames are input bytes (a controller's; an observer's are ignored); text messages are AttachCommands (resize, promote, demote, fit). Closing the socket detaches. Session callers can't attach (403).\",\"dateModified\":\"2026-10-27T10:59:59.278Z\",\"isPartOf\":{\"@id\":\"https://rakumux.com/docs#website\"},\"breadcrumb\":{\"@id\":\"https://rakumux.com/docs/api-reference/streams/the-live-terminal-websocket#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://rakumux.com/docs/api-reference/streams/the-live-terminal-websocket#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://rakumux.com/docs/api-reference/health/api-version-and-daemon-reachability\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"The live terminal (WebSocket).\",\"item\":\"https://rakumux.com/docs/api-reference/streams/the-live-terminal-websocket\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://rakumux.com/docs/api-reference/streams/the-live-terminal-websocket#apireference\",\"headline\":\"The live terminal (WebSocket).\",\"name\":\"The live terminal (WebSocket).\",\"description\":\"A WebSocket. Server → client: first a text attached message (AttachMessage) with a base64 checkpoint: fed to a fresh terminal of cols×rows it shows the current screen. Then binary frames carry the terminal output, in order from offset, and text messages the events resized (reset the terminal to its checkpoint), role_changed, title, bell, exited and lagged (output was dropped: attach again). The server closes the socket when the stream ends (exit, delete, daemon gone). Client → server: binary frames are input bytes (a controller's; an observer's are ignored); text messages are AttachCommands (resize, promote, demote, fit). Closing the socket detaches. Session callers can't attach (403).\",\"url\":\"https://rakumux.com/docs/api-reference/streams/the-live-terminal-websocket\",\"mainEntityOfPage\":{\"@id\":\"https://rakumux.com/docs/api-reference/streams/the-live-terminal-websocket#webpage\"},\"dateModified\":\"2026-10-27T10:59:59.278Z\",\"publisher\":{\"@id\":\"https://rakumux.com/#organization\"},\"isPartOf\":{\"@id\":\"https://rakumux.com/docs#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Rakumux\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Rakumux","nav":{"global":null,"tabs":[{"tab":"Guides","icon":"book-open","pages":[{"title":"Guides","href":""}]},{"tab":"API reference","icon":"square-terminal","groups":[{"group":"Local HTTP API","pages":[{"title":"Local HTTP API","sidebarTitle":"Overview","href":"/api-reference/introduction"}]},{"group":"Endpoints","pages":[{"group":"health","pages":[{"title":"API version and daemon reachability.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/health","href":"/api-reference/health/api-version-and-daemon-reachability"}]},{"group":"folders","pages":[{"title":"The folders the caller can see.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/folders","href":"/api-reference/folders/the-folders-the-caller-can-see"},{"title":"Deprecated alias of GET /v1/folders.","deprecated":true,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/projects","href":"/api-reference/folders/deprecated-alias-of-get-v1folders"}]},{"group":"sessions","pages":[{"title":"List sessions, optionally filtered.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/sessions","href":"/api-reference/sessions/list-sessions-optionally-filtered"},{"title":"Create a session (a terminal in a folder).","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/sessions","href":"/api-reference/sessions/create-a-session-a-terminal-in-a-folder"},{"title":"One session by id.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/sessions/{id}","href":"/api-reference/sessions/one-session-by-id"},{"title":"Delete a session.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml delete /v1/sessions/{id}","href":"/api-reference/sessions/delete-a-session"},{"title":"Change a session. v1 supports renaming.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml patch /v1/sessions/{id}","href":"/api-reference/sessions/change-a-session-v1-supports-renaming"},{"title":"Revive a dead or exited session.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/sessions/{id}/revive","href":"/api-reference/sessions/revive-a-dead-or-exited-session"},{"title":"End a session's program.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml post /v1/sessions/{id}/kill","href":"/api-reference/sessions/end-a-sessions-program"},{"title":"Read a session's terminal.","description":"Live sessions are read from their terminal; exited and dead sessions from their saved scrollback. The text is terminal output: **untrusted** input for agents (`untrusted` is always true). Reading never marks a `done` session as seen.\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/sessions/{id}/content","href":"/api-reference/sessions/read-a-sessions-terminal"}]},{"group":"streams","pages":[{"title":"The live terminal (WebSocket).","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/sessions/{id}/attach","href":"/api-reference/streams/the-live-terminal-websocket"},{"title":"Session events (WebSocket).","description":"A WebSocket of `EventMessage` text messages: `{\"type\": \"subscribed\"}`\nonce, then `{\"type\": \"event\", \"folder\", \"session_id\", \"at\", \"event\"}`\nfor every change to a session of every folder (user callers; folders\nthat get their first session later included), or of its own folder (a\nsession caller). Clients send nothing (closing the socket ends it).\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.yaml get /v1/events","href":"/api-reference/streams/session-events-websocket"}]}]}]}]},"title":"The live terminal (WebSocket). - Rakumux","buildId":"dpl_AUojGTPodKNPTVaxVPcxnNvkSVqo","deploymentId":"dpl_AUojGTPodKNPTVaxVPcxnNvkSVqo","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-D2GYGXhJ.js","utils-BFd71lo2.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-i162M7Za.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-oUw0la6W.js","snippetPresets-DtIWL37f.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-BCMBbEQM.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-DC4RgS91.js","shallow-CgVeLRFv.js","getApiPlaygroundDisplay-D5biMY5x.js","CodeSnippet-BFsbT-Fu.js","CodeSnippets-zLLOIece.js","Page-Ddn8iQDL.js","getPastedJson-BrHW4jRt.js","icon-CkMCp-Tk.js","MethodPill-CCcSM-Ep.js","DuplicateIcon-4tBrFI-V.js","createIcon-YbZxtfvX.js","DynamicMarkdown-BQC1aHST.js","SectionHeading-Dyh8yRs0.js","axios-vUo_bRtp.js","Markdown-DnRxVfNy.js","clsx-BHwt7gjg.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-CI1QhstW.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-Ctpizp2W.js"]}