Relay protocol and transport
The relay is the host-side bridge between application clients and runtime services. It gives desktop, mobile, command-line, and remote clients one request model for workspace data, Git work, terminals, and host actions while keeping live host resources tied to the right caller and connection.
System role
The relay separates the client that asks for work from the host that owns the work. Local clients use the runtime service directly. Remote clients use an authenticated desktop or runtime socket, and the relay can forward a request to a selected execution host instead of running it on the wrong machine. See the desktop app platform page for the wider platform view and the command-line and headless runtime page for non-desktop clients.
Resource ownership
The host service owns workspaces, live PTYs, and the endpoint that reaches them. A client owns only its connection-scoped subscriptions, capabilities, and request state. This split lets a new client attach to an existing terminal after a renderer or network failure instead of creating a second shell.
The relay keeps control work separate from terminal stream work. Control calls use request IDs and replies. Stream work uses ordered events or binary frames. A terminal output flood therefore does not turn every control call into a bulk-data operation.
References: src/…/core.ts• L92-173 src/…/runtime-rpc-lifecycle.ts• L53-83 src/…/runtime-rpc-binary-routing.ts• L13-31
Transport families
The runtime gives the same RPC meaning to several links. Local Unix sockets and named pipes carry newline-delimited JSON. WebSockets carry paired or remote traffic through an encrypted channel and can carry text or binary messages. The server starts the local link first, then adds the WebSocket link when pairing identity is ready.
| Client path | Main purpose | Message form |
|---|---|---|
| Unix socket or named pipe | Local runtime RPC | Newline-delimited JSON |
| WebSocket | Paired, mobile, and remote runtime access | Encrypted text and binary messages |
| Binary terminal channel | Terminal output and control | Length-framed terminal messages |
Each transport owns its connection limits, timeouts, close handling, and message-size limits. The dispatcher receives the same request and caller context regardless of the link.
References: src/…/unix-socket-transport.ts• L1-22 src/…/runtime-rpc-lifecycle.ts• L35-83 src/…/e2ee-channel.ts• L49-103
Connection lifecycle
The connection lifecycle admits a client only after it proves its credential and transport identity. The server publishes discoverable metadata only after its live endpoints are ready, then removes or replaces that metadata when ownership changes.
Runtime startup and discovery
The runtime server creates its local endpoint, prepares optional WebSocket pairing, records the active transports, and writes runtime metadata. A metadata write failure stops the transports so the runtime cannot serve while remaining undiscoverable. The server also watches metadata ownership so a dead runtime does not leave a stale endpoint in place.
Startup treats WebSocket access as supplementary to the local link unless a pinned port is required. This keeps local CLI work available when network binding fails, while still allowing paired clients to use the same RPC surface when pairing is healthy.
References: src/…/runtime-rpc-lifecycle.ts• L35-161 src/…/runtime-rpc-socket-metadata.ts• L1-80 src/…/runtime-rpc.ts• L1-9
Local admission
The local link reads one JSON request per line and checks the shared token from runtime metadata before dispatch. It limits connections and retained message bytes. Each request has its own abort signal, so closing a socket stops work owned by that socket without canceling sibling requests.
Long polls opt into keepalive messages and use bounded admission slots. Short calls do not consume those slots. This preserves room for quick status or control calls when a small number of clients hold long waits.
References: src/…/unix-socket-transport.ts• L25-70 src/…/unix-socket-transport.ts• L97-221 src/…/runtime-rpc-request-admission.ts• L18-60 src/…/runtime-rpc-long-poll.ts• L5-76
Remote authentication and routing
The WebSocket path completes an encrypted handshake before it exposes RPC. It supports a versioned session, authenticates a paired device or device key, and stores the device scope and client capabilities on that socket. The request cannot replace those facts with a token or scope supplied in its body.
An authenticated mobile request may name an execution host. The desktop relay forwards only methods allowed for that route and only to a configured host. An invalid or unreachable target returns an error instead of falling back to local execution.
sequenceDiagram
participant Client as Client
participant Relay as Runtime relay
participant Host as Selected runtime
Client->>Relay: WebSocket hello
Relay-->>Client: Encrypted session ready
Client->>Relay: Device authentication and capabilities
Relay-->>Client: Authenticated scope
Client->>Relay: RPC request
Relay->>Host: Forward when execution host requires it
Host-->>Relay: Reply or stream frames
Relay-->>Client: Bounded encrypted reply or stream
References: src/…/e2ee-channel.ts• L184-277 src/…/runtime-rpc-websocket-dispatch.ts• L34-100 src/…/runtime-rpc-websocket-dispatch.ts• L103-190 src/…/device-principal.ts• L5-31
Request protocol
The request protocol gives each call a method name, request ID, parameters, and a result or structured error. A unary call has one reply. A streaming call keeps the request ID while emitting several replies or binary stream frames. Replies include the runtime identity that produced them.
Method registry
The method registry is the shared product contract for local and remote clients. Each method declares its public name, caller permission, parameter schema, optional startup requirement, and unary or streaming result mode. Duplicate names fail registry creation, so two transports cannot silently expose different meanings for one method.
The runtime method surface includes workspace and worktree operations, filesystem and Git actions, terminal control, browser-host work, pairing, and orchestration. A host can remove methods it does not serve before requests reach the dispatcher.
References: src/…/core.ts• L175-215 src/…/core.ts• L234-278 src/…/repo.ts• L41-55 src/…/worktree.ts• L41-53
Request admission and dispatch
The dispatcher is the common path for unary and streaming calls. It checks the caller scope, method availability, transport support, runtime source, parameters, and required startup readiness before it invokes a handler. It then builds a context that carries the authenticated caller, cancellation signal, capabilities, and binary handlers.
The flow turns a request into one of three outcomes: a structured refusal before host work starts, one bounded result, or a sequence of streaming results. Streaming replies are marked as such and are emitted through the transport callback, which keeps object replies separate from wire encoding.
flowchart LR
A[Request] --> B[Credential and caller scope]
B --> C[Method and transport checks]
C --> D[Source and parameter checks]
D --> E[Startup readiness]
E --> F{Result mode}
F -->|Unary| G[One structured reply]
F -->|Streaming| H[Ordered replies or binary frames]
References: src/…/runtime-rpc-request-admission.ts• L129-166 src/…/dispatcher.ts• L67-183 src/…/core.ts• L92-173 src/…/dispatcher-streaming-feature-emitter.ts• L7-26
Caller scope and capabilities
Caller scope is the permission boundary stamped by the transport. The owner CLI, a paired runtime client, and a mobile client have different method access. A delegated phone cannot gain pairing administration through its parent desktop, and an unknown mobile method is rejected as unavailable.
Capabilities are support evidence for one authenticated connection. They allow additive features such as binary terminal streams, output acknowledgements, input acknowledgements, compressed frames, and newer host services without making every client upgrade at once. Stream encoding uses the capabilities present when that stream opens.
References: src/…/rpc-caller-scope.ts• L1-47 src/…/device-principal.ts• L15-31 src/…/runtime-client-capabilities.ts• L3-51 src/…/stream-schemas.ts• L6-32
Cancellation and long polls
Connection close is part of the request contract. The relay passes an abort signal to long work, terminal waits, browser-host waits, and other operations that can outlive a short call. A closed client therefore releases its waiters and subscriptions instead of leaving host work attached to a dead link.
Long-poll classes have shared and specialized caps. The relay returns a busy error when a cap is full, then releases the slot when the request settles or the connection closes. Cancellation remains distinct from refusal because a canceled operation may already have changed host state.
References: src/…/runtime-rpc-long-poll.ts• L17-76 src/…/runtime-rpc-request-admission.ts• L35-60 src/…/runtime-rpc-binary-routing.ts• L33-86 src/…/core.ts• L92-124
Backpressure and flow control
The relay carries small control messages beside terminal output and large workspace results. It uses byte limits, bounded queues, output priority, pause signals, and acknowledgements so a slow client cannot freeze interactive input or grow host memory without limit.
Reply and stream limits
Local requests stop growing when a frame exceeds the local message limit. Remote replies pass through a size and outbound-memory budget before encryption and WebSocket send. When a reply cannot be delivered safely, the relay closes or detaches the unsafe path instead of presenting a partial result as complete.
The same rule applies to terminal snapshots. The relay measures the full frame, including metadata, before it sends it. Compression can reduce a negotiated remote frame, but it does not remove the size and queue checks.
References: src/…/unix-socket-transport.ts• L126-155 src/…/e2ee-channel.ts• L298-316 src/…/mobile-e2ee-v2-desktop-outbound.ts• L16-53 src/…/runtime-rpc-reply-size-limit.ts• L1-80
Terminal output windows
Remote terminal output can use a per-stream byte window and a connection-wide byte window. The client acknowledges bytes that it has accepted. The relay then drains pending output in round-robin order so one busy terminal cannot starve the other streams on the same connection.
If pending output exceeds its budget, the relay sends a bounded recovery snapshot. That snapshot replaces the client's old screen and covers output through a known sequence. If the relay cannot prove a complete replacement, it detaches the affected stream or connection rather than showing an unverifiable screen.
References: src/…/terminal-multiplex-frame-delivery.ts• L103-156 src/…/terminal-multiplex-flow-control.ts• L23-186 src/…/terminal-subscribe-binary.ts• L123-163
Producer pauses and data gaps
The host can pause a PTY producer when queued output crosses its high limit and resume it below its low limit. A stalled or unreachable stream may lose transient output, but the relay keeps a safe tail and marks the gap so the client asks for an authoritative snapshot instead of treating missing bytes as process exit.
Pause and resume notifications are best effort. The daemon-side stall bound remains the final safety limit, so a lost notification cannot leave a shell paused forever.
References: src/…/daemon-stream-backpressure.ts• L4-7 src/…/daemon-stream-backpressure.ts• L78-148 src/…/daemon-stream-data-batcher.ts• L152-265
Filesystem and Git operations
Filesystem and Git work runs on the host that owns the selected workspace. Runtime RPC exposes the same product-level operations to local, remote, and mobile clients. A result can be one reply, a bounded stream, or a watch subscription.
Workspace selection
Every workspace operation carries a repository or worktree selector. The host resolves that selector to an authorized execution host before it reads or changes a path. This keeps a path name from making a remote workspace look like a local one.
The same selection rule supports repository discovery, worktree creation and removal, branch actions, and startup-agent work. Retries can carry a client mutation ID so a reconnect does not create a duplicate workspace.
References: src/…/repo.ts• L135-187 src/…/worktree.ts• L104-152 src/…/runtime-rpc-websocket-dispatch.ts• L43-99
Filesystem access and mutation
The filesystem surface supports directory and metadata reads, file content, path and content search, watches, and safe mutations. Reads and searches use request-scoped content budgets. Directory pages and watches are tied to the connection so close cleanup can stop slow work.
Large remote saves use bounded chunks and a temporary sibling. The final promotion checks the original target precondition and the socket that began the save. This prevents a stale client from overwriting newer content or completing another client's partial save.
References: src/…/files.ts• L38-72 src/…/files-read-dir-page.ts• L38-86 src/…/files-staged-save-methods.ts• L10-49 src/…/file-watch-stream-lifecycle.ts• L39-123
Git operations
The Git surface covers status, history, diffs, conflicts, branch movement, staging, commits, remote sync, and worktree actions. Each request names the worktree or repository instead of assuming that the application process is the execution host.
Status, diff, and history results use cancellation and content limits for remote clients. The client receives enough structure to show the change while a large repository cannot monopolize the relay.
References: src/…/git.ts• L26-61 src/…/git.ts• L77-132 src/…/git-diff-methods.ts• L5-57 src/…/remote-rpc-content-budget.ts• L18-25
PTY stream delivery
The PTY service creates host shells and exposes their state through control requests and a live output stream. Clients can create or attach, write input, resize, pause, resume, inspect, request snapshots, and close sessions. A terminal stream starts from a bounded screen state and then follows live output.
Terminal subscriptions
terminal.subscribe registers cleanup before it waits for a PTY. This lets unsubscribe, socket close, stream replacement, or PTY exit end the wait. Desktop clients can use JSON or binary output. Mobile clients must use binary output, and a mobile input lease can receive input authority without opening a second output view.
The subscription owns its listeners, viewport claim, mobile presence, binary handler, and teardown. A replacement connection therefore removes the old stream state instead of leaving a hidden listener on the live PTY.
References: src/…/terminal-subscribe-method.ts• L13-55 src/…/terminal-subscribe-method.ts• L57-141 src/…/terminal-subscribe-json-and-lease.ts• L9-26
Snapshot and live output
The stream sends a bounded snapshot before live output. The snapshot carries terminal size, display state, and an output sequence when the host can provide an authoritative model. Output received while the snapshot is prepared is buffered and joined by sequence.
If buffered output overflows, the relay favors a fresh authoritative snapshot over an incomplete screen. A reconnecting client therefore restores from host state and resumes live output instead of guessing from the last bytes on an unreliable link.
References: src/…/terminal-subscribe-binary-snapshot.ts• L21-75 src/…/terminal-subscribe-binary-snapshot.ts• L158-320 src/…/terminal-multiplex-initial-snapshot.ts• L30-151
Multiplexed terminal streams
terminal.multiplex carries many logical terminal streams over one authenticated binary channel. Each stream has its own stream ID, output state, acknowledgement window, cleanup, and PTY wait. The connection also has a total output window so many streams cannot defeat the link budget together.
The channel accepts subscribe, input, resize, pause, snapshot, acknowledgement, and unsubscribe frames. It drains output in round-robin order. A paused or overflowing stream drops only its own transient output and receives a drop notice or recovery snapshot when the client supports it.
flowchart LR
A[Multiplex channel] --> B[Stream ID and subscription]
B --> C[Initial snapshot]
C --> D[Live output queue]
D --> E{Window has room?}
E -->|Yes| F[Send output frame]
E -->|No| G[Hold bounded output]
G --> H{Budget exceeded?}
H -->|No| D
H -->|Yes| I[Send recovery snapshot or detach]
References: src/…/terminal-multiplex-method.ts• L18-79 src/…/terminal-multiplex-subscribe-frame.ts• L10-67 src/…/terminal-multiplex-stream-initialization.ts• L21-158 src/…/terminal-multiplex-flow-control.ts• L23-186
Terminal input and viewport
Input and resize use the control side of the terminal service or binary stream frames. The host checks the live terminal identity, caller source, and current input or viewport authority before applying them. A stale handle or a client without the input floor receives a refusal.
Sequenced input uses a client session ID and acknowledgements. The client can resend after a lost acknowledgement without replaying an input that the host already applied. If bytes may have reached the provider but settlement is uncertain, the relay reports an uncertain delivery rather than a false refusal.
References: src/…/terminal-input-delivery.ts• L69-129 src/…/terminal-multiplex-input-frame.ts• L13-59 src/…/terminal-subscribe-binary-control-frames.ts• L39-139
Change checklist
When these files or sections are changed, remember to consider these:
- Keep runtime metadata, local token admission, WebSocket pairing identity, and active transport publication aligned. A live endpoint that is missing from metadata cannot be discovered safely.
- Keep the server's local and WebSocket lifecycle paths aligned with the moved
src/main/runtime/rpc/server/ownership. A path move must not leave pairing, shutdown, or binary routing on an old server path. - Keep caller scope, device principal, method permission, mobile allowlist, execution-host routing, and dispatcher checks aligned. Do not accept authority from request fields.
- Keep capability names, terminal stream schemas, opening stream format, and binary handler registration aligned. A client must not decode a stream with capabilities from a later connection update.
- Keep long-poll classification, admission caps, keepalive start, abort signals, and slot release aligned. A new wait can either hold a socket without a keepalive or consume capacity forever if one path is missed.
- Keep reply-size limits, encrypted outbound budgets, compression negotiation, and close behavior aligned. Never silently drop a reply that the caller treats as complete.
- Keep terminal stream IDs, output sequence domains, per-stream and total acknowledgement windows, pause notices, and recovery snapshots aligned.
- Keep snapshot metadata, output sequence coverage, byte measurement, and client replay rules aligned. A snapshot must replace exactly the output that the client can no longer verify.
- Keep workspace selectors, execution-host resolution, path authorization, filesystem budgets, staged-save ownership, and Git cancellation aligned.
- Keep PTY subscription cleanup, input session IDs, live terminal identity checks, viewport claims, and endpoint-loss notices aligned across JSON and binary streams.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Runtime metadata is written before all live endpoints are ready | A client connects to an endpoint that cannot serve the advertised runtime | Publish metadata only after active transports are recorded |
| Local request exceeds the frame limit | The request is rejected before it can grow the host buffer | Bounded NDJSON retention and request_too_large |
| Remote authentication or decryption does not finish | The socket never exposes RPC or closes the unsafe session | Versioned encrypted handshake, device authentication, and failure threshold |
| A request supplies a different device token or scope | The caller could reach work outside its paired grant | Bind scope and identity to the authenticated socket |
| A remote execution host is invalid or unavailable | Work could run on the wrong machine or appear to succeed locally | Allowlisted routing and explicit unavailable errors |
| Long-poll capacity is full | A wait is rejected while short RPCs remain available | Shared and specialized long-poll caps |
| A client stops acknowledging terminal output | Output waits or exceeds the stream budget | Per-stream and total windows with bounded recovery |
| Pending terminal output loses a sequence range | The client displays an incomplete screen | Authoritative recovery snapshot or stream detach |
| A client closes during a filesystem, Git, or PTY wait | Host work can continue after its owner is gone | Connection abort signals and subscription teardown |
| A staged save loses its owning socket or target changes | Partial data can remain or replace newer content | Socket ownership, idle cleanup, size limits, and commit precondition |
| A terminal handle names an old process incarnation | Input or resize can affect a recycled shell | Live handle and incarnation checks |
Key files
| File | Why to read it |
|---|---|
| src/…/runtime-rpc-lifecycle.ts | Runtime startup, transport publication, pairing setup, and connection cleanup |
| src/…/runtime-rpc-request-admission.ts | Local authentication, long-poll admission, and dispatcher entry |
| src/…/runtime-rpc-websocket-dispatch.ts | Paired-device admission, execution-host routing, and remote dispatch context |
| src/…/e2ee-channel.ts | Encrypted handshake, device authentication, capabilities, and outbound limits |
| src/…/unix-socket-transport.ts | Local NDJSON framing, connection limits, keepalives, and abort-on-close behavior |
| src/…/core.ts | RPC request, response, caller context, method, and stream contracts |
| src/…/dispatcher.ts | Shared unary and streaming dispatch flow |
| src/…/rpc-caller-scope.ts | Caller permissions and mobile method boundaries |
| src/…/files.ts | Workspace filesystem reads, searches, mutations, and watches |
| src/…/git.ts | Workspace Git read and mutation surface |
| src/…/terminal-subscribe-method.ts | Terminal subscription choice, registration, and cleanup |
| src/…/terminal-subscribe-binary-snapshot.ts | Initial terminal state, buffering, and recovery snapshots |
| src/…/terminal-multiplex-method.ts | One binary channel carrying many terminal streams |
| src/…/terminal-multiplex-flow-control.ts | Acknowledgement windows, round-robin draining, and recovery |
| src/…/terminal-input-delivery.ts | Input authority, write settlement, and uncertain delivery |
| src/…/stream-schemas.ts | Terminal stream capability and control-frame contract |