API Reference
The pane WebSocket
GET /pty, an asymmetric protocol, and the close codes that must never be retried.
The implementation is torta’s own: RFC 6455 version 13, no deflate, no extensions, no subprotocols.
The handshake
GET /pty?agent=<name>&attach=1&cols=120&rows=32| Parameter | Meaning |
|---|---|
agent |
which agent’s pane to open or attach to |
attach |
1 means never spawn a session, only attach |
cols |
terminal width, optional |
rows |
terminal height, optional |
Opening without attach=1 starts a session. Every retry must be
attach-only.
Refusals before the upgrade
A refusal is a real HTTP response:
| Code | Reason |
|---|---|
| 400 | no such websocket route, for any path other than /pty |
| 403 | cross-origin websocket handshakes are refused |
| 409 | there is no workspace here yet, in wizard mode |
The upgrade itself is refused when Upgrade is not websocket, when
Connection does not request an upgrade, when Sec-WebSocket-Version is not
13, or when Sec-WebSocket-Key is missing or is not 16 bytes once decoded.
Framing
Down, from the server: raw terminal bytes in text frames, with no envelope.
Up, from the client: JSON.
| Message | Meaning |
|---|---|
{"t":"in","d":"ls\r"} |
send these characters to the terminal |
{"t":"resize","cols":120,"rows":32} |
resize the terminal |
{"t":"ping"} |
liveness check |
A binary frame sent up is treated as raw input, decoded as UTF-8.
The answer to a ping is {"t":"pong"} sent as a binary frame.
Close codes
| Code | Meaning | Retry? |
|---|---|---|
| 1000 | the board closed the pane deliberately | never |
| 4404 | no session, and attach=1 was set |
never |
| 4500 | a pane could not be opened | never |
| anything else | the transport dropped | yes, attach-only |
When a pane cannot be opened, the reason is written into the terminal in red before the socket closes.
Limits
- A control frame is at most 125 bytes and may not be fragmented.
- A fragmented message may accumulate up to 4 MB before the connection is dropped.
The client’s policy
The board’s own reconnect rules ship as a separate module:
- ping every 15 seconds
- treat 40 seconds of silence as a dead link
- back off through 400ms, 900ms, 2s, 4s, 8s, then hold at 15s
- never reconnect after 1000, 4404 or 4500