Terminal WebSocket
A worktree's console in Jaah is a live terminal on the node that hosts the worktree. The browser reaches it over one WebSocket, which relays bytes both ways without reading them: what you type goes to the terminal, and what the terminal prints comes back. Opening a worktree's console in Jaah opens this connection; How worktrees work describes the worktrees themselves.
Opening a connection
Opening a terminal takes two requests: one that prepares the connection, then the WebSocket itself.
1. Ask for a connection. Send a POST from a page of the Jaah console:
POST /api/console/{project}/{number}/open
| Part | Meaning |
|---|---|
{project} | The project's numeric id, not its name: the number at the end of its settings page's address. |
{number} | The worktree's number within that project. |
Query parameters, all optional:
| Parameter | Meaning |
|---|---|
cols, rows | The terminal's starting size in characters. Each from 1 to 1000; the node picks a size when they are absent or out of range. |
node | The id of the node that hosts the worktree. Send it when two nodes have a worktree with the same project and number. |
provider | Which provider's agent account Jaah picks for the console: claude, codex, deepseek, antigravity or pi. Each only when your organization's plan includes it; otherwise the open is refused with 4404. Leave it out to let Jaah pick. |
The console sends a few more parameters for its own views; you do not need them. A request sent from another site is refused.
On success the answer is 200 with the path to connect to:
{"url": "/api/console-relay?ticket=…"}
When Jaah refuses, the answer carries the close code you would otherwise have received, a reason, and
detail, one line to show the user:
{"close_code": 4404, "reason": "unknown provider", "detail": "unknown provider"}
Read close_code exactly as a close code from the socket (see Close codes). The HTTP
status (401, 404, 409 or 503) only mirrors it.
A refusal that comes before the console is reached carries no close_code, only the usual
error body with detail: 401 when you are not signed in, 403 when you may
not view worktrees or your address is outside your organization's IP allowlist, 409 when the tab switched organization. Treat these as 4401.
2. Open the WebSocket at that path on the same host:
wss://<your Jaah host>/api/console-relay?ticket=…
Use ws:// instead when the console itself is served over plain http://. The ticket works once,
only from the same console session that sent the POST, and expires 90 seconds after Jaah issues it during the POST, so connect
as soon as the answer arrives. A ticket used otherwise closes the socket with 4503. To reconnect, send a new POST for a new
ticket.
Frames
Every frame is binary. The two directions are shaped differently.
From the terminal to you, frames are the terminal's raw output: bytes to feed to a terminal emulator as they arrive, in order. A frame can end in the middle of a character or an escape sequence, so do not decode each frame on its own. An empty frame is not output: it answers your keepalive (below), and tells you the connection is still alive while the terminal prints nothing.
From you to the terminal, each frame is a 3-byte header followed by its payload:
| Byte | Meaning |
|---|---|
| 0 | Frame type |
| 1–2 | Payload length, big-endian, at most 65,535 |
| 3… | Payload |
| Type | Payload |
|---|---|
0 input | Bytes to type into the terminal, as UTF-8. Split long input over several frames. |
1 resize | 4 bytes: columns (2 bytes, big-endian), then rows (2 bytes, big-endian), each from 1 to 1000; a frame outside that is ignored. |
Types 2 and 3 carry images pasted into the console. Type 4, with an empty payload, asks for the
text of the whole pane: it comes back in the terminal's output as a clipboard escape sequence (OSC 52).
The node answers one copy request at a time, at most one a second, with up to the newest 4 MiB of
output; it ignores type 4 from a read-only viewer and on a MicroVM console. The console uses these three
itself.
Keep the connection busy. A connection with no traffic can be dropped by a proxy on the way, and
after 30 minutes in which the terminal prints nothing and no viewer who can type sends a frame, the node
disconnects every viewer (the session keeps running; reconnect to see it again). A view-only viewer's
frames do not count. Separately, Jaah closes the connection with 4503 once it has received no frame
from you for 2 minutes, view-only or not. So send an empty input frame (the three bytes 00 00 00)
every 25 seconds, as the console does; each one is answered with an empty frame.
In an organization with HIPAA turned on, the console also closes with 4408 after 15 minutes without
typing. Only an input or paste frame (type 0, 2 or 3) with a payload counts as typing: the empty
keepalive frame and resize frames keep the connection open but do not reset this timer.
When you may only view a worktree, the console is one-way: the connection opens, you receive the terminal's output, and every frame you send — resize included — is dropped.
Which session it attaches to
The console attaches to the session a task is running in the worktree; it never starts one. A worktree
no task holds has no session: opening its console is refused with 4502 and the detail
This slot is free. A console opens only on a task's slot. A held worktree whose session has ended is
refused with 4502 and the detail No session running on this slot.
One session takes at most 16 viewers at a time. A 17th open is refused with 4503 and the reason
too many concurrent viewers; it succeeds once another viewer closes.
When nobody who can type is connected, viewers who may only view share one view-only terminal. When someone
who can type opens the same worktree, the node replaces that terminal with one they can type in and closes
each view-only connection with 4503. Reconnect to keep watching: a view-only viewer who connects while
someone who can type is there joins their terminal, and still cannot type.
Close codes
Every connection ends with one of these codes, either as the socket's close code or as the close_code
of a refused POST. The Reconnect? column says whether trying again can help.
| Code | Meaning | Reconnect? |
|---|---|---|
1000 | The terminal session ended. | No — open the console again once a task runs there. |
4401 | Connection refused, or your access ended while the terminal was open. | No. |
4403 | Your address is no longer on your organization's IP allowlist. The close reason says so. A new connection from that address is refused at the POST with 403; a WebSocket dialled from an address outside the allowlist is refused with 4503. | No — an org admin must add the address first. |
4404 | No such worktree, one you cannot open, or a query parameter value it does not accept. | No. |
4408 | Closed after 15 minutes without typing, in an organization with HIPAA turned on. The session keeps running. | No — open the console again to reattach. |
4502 | The node has no session to attach to, or cannot provide this console. | No, on a first connection. After a drop it means the session is gone: a worktree's console keeps trying to reattach every 10 seconds. |
4503 | The connection to the node failed or broke, the ticket was not valid, the session already has 16 viewers, or a view-only terminal was replaced (see Which session it attaches to); any session on the node is untouched. A refused POST or ticket says why in its reason; a close after the connection opened may carry no reason. | Yes — reconnect. |
Any other code — 1006 when the network drops, or 1012 while Jaah restarts — is a lost connection:
reconnect. The close reason, when there is one, is a short readable explanation.
Example — open a terminal and handle its close code
Paste this into the browser console on a page of the Jaah console. Replace the project id and number with a worktree you can open; the output prints as text.
const projectId = 7
const number = 1
const RETRYABLE = new Set([4503, 1006, 1012])
const KEEPALIVE = new Uint8Array([0, 0, 0]) // an empty input frame
async function connect() {
// 1. Ask for a connection: the answer is a one-time path, or a refusal with its close code.
const open = `/api/console/${projectId}/${number}/open?cols=120&rows=40`
const answer = await fetch(open, { method: 'POST' })
const body = await answer.json()
if (!answer.ok) {
const code = body.close_code ?? 4401 // a refusal before the console is reached has only `detail`
console.log(`refused: ${code} ${typeof body.detail === 'string' ? body.detail : JSON.stringify(body.detail)}`)
if (RETRYABLE.has(code)) setTimeout(connect, 1000)
return
}
// 2. Open the WebSocket at that path.
const proto = location.protocol === 'https:' ? 'wss:' : 'ws:'
const socket = new WebSocket(`${proto}//${location.host}${body.url}`)
socket.binaryType = 'arraybuffer'
const decoder = new TextDecoder() // streaming decode: frames can split a character
const keepalive = setInterval(() => {
if (socket.readyState === WebSocket.OPEN) socket.send(KEEPALIVE)
}, 25000)
socket.addEventListener('message', (frame) => {
if (frame.data.byteLength === 0) return // the answer to a keepalive, not output
console.log(decoder.decode(new Uint8Array(frame.data), { stream: true }))
})
socket.addEventListener('close', (closed) => {
clearInterval(keepalive)
console.log(`closed: ${closed.code} ${closed.reason}`)
if (RETRYABLE.has(closed.code)) {
setTimeout(connect, 1000) // the session is still running: attach to it again
}
})
window.terminal = socket
}
// Type into the terminal: a type-0 frame.
function send(socket, text) {
const payload = new TextEncoder().encode(text)
const frame = new Uint8Array(3 + payload.length)
frame[0] = 0
frame[1] = payload.length >> 8
frame[2] = payload.length & 0xff
frame.set(payload, 3)
socket.send(frame)
}
connect()
// Once it is open: send(window.terminal, 'ls\r')
A worktree that does not exist is refused at once and prints refused: 4404.