Skip to main content

wsh Architecture

This page explains how the pieces of the desktop app talk to each other: the Electron main process, the on-screen renderer, the wavesrv backend, and the wsh command line tool running locally or on a remote host. It is written for a curious user, not as a line-by-line code tour — see wsh Command and wsh Reference for the user-facing side of wsh.

The four pieces​

Architecture diagram: Electron talks to local wavesrv, which routes operations to local or remote wsh.
Architecture diagram: Electron talks to local wavesrv, which routes operations to local or remote wsh.View full size ↗
  • Electron main process — the native shell of the app. It creates windows, owns the system tray and native menus, and starts everything else. It never talks directly to your shell or SSH hosts; it delegates that to wavesrv.
  • Renderer — the web page inside each window: the React UI you interact with (tabs, panes, widgets, the terminal view itself). It has no direct access to the filesystem or processes; every action goes out over one of the channels below.
  • wavesrv — a Go process that the Electron main process spawns as a child on every launch. It owns your local SQLite database, your terminal sessions, your SSH/WSL connections, and the RPC router that everything else plugs into. If wavesrv exits, the app shuts itself down (there is no headless recovery).
  • wsh — the command line tool ( cmd/wsh ) you can run inside any terminal block. It is a small client to the same RPC system wavesrv runs, whether the terminal is local or on a remote host over SSH.
Electron main  --spawns-->  wavesrv (Go)
| | \
(native OS calls) SQLite RPC router
| | \
Renderer <--WebSocket/HTTP--+ wsh (local or remote)

How the renderer reaches wavesrv​

The renderer never opens a raw socket. It uses two channels, both authenticated the same way:

  • /wave/service (HTTP) — a single endpoint used for request/response calls: creating a tab, updating a setting, moving a block. The server dispatches these by reflection, looking up a service name and method name (pkg/service/service.go) and calling the matching Go function. This is what WOS.callBackendService(...) on the frontend ultimately hits.
  • /ws?tabid=<id> (WebSocket) — a persistent connection per tab used for everything that isn't a direct request/response: live updates to objects (tabs, blocks, workspaces), terminal output, and process events. The frontend subscribes to individual objects with wpsSubscribeToObject() and gets pushed updates as they happen; it does not poll.

Authentication. Each time the app starts, the Electron main process generates a random key in memory and passes it to wavesrv as the TERMIA_AUTH_KEY environment variable. It then silently attaches that same value as an X-AuthKey header on every request the renderer sends to wavesrv's HTTP and WebSocket endpoints. wavesrv rejects anything without a matching header. Because the key is generated fresh per run and only shared between the two processes on your machine, nothing outside your own app can call into wavesrv.

wavesrv prints its listening address as soon as it is ready (a line containing WAVESRV-ESTART); the Electron main process parses that line to learn which local port to point the renderer at before it loads the page.

Where the pushed updates come from. Internally, wavesrv has a small publish/subscribe broker that anything on the backend can post an event to — an object changing, a terminal producing output, a connection's status flipping. The broker matches each event against which route ids have subscribed to that kind of event, and hands it to the same RPC router described below, which forwards it out over the WebSocket connection for the tab that asked for it. This is why the frontend's object subscriptions feel instant: it isn't polling wavesrv, it's sitting on an open connection waiting to be told.

The wsh RPC layer​

Inside wavesrv, all backend features are exposed as RPC commands (the full list lives in pkg/wshrpc/wshrpctypes.go) and dispatched by a router that keys traffic by route id — a string like conn:<connection-name> for a specific SSH/WSL connection, controller:<blockId> for the process behind a running block, or tab:<tabId> for a tab. Anything that can hold an RPC connection — the renderer, a terminal block's controller, or a wsh process — registers itself under a route id, and the router forwards messages to whichever route they are addressed to. This is the same mechanism whether the caller is the UI itself or a wsh command you type by hand.

wsh on your local machine​

When you run wsh inside a local terminal block, it connects to a Unix domain socket named wave.sock inside the app's data directory (see emain/platform.ts for the exact path per OS) and authenticates with a signed token that wavesrv handed the block when it started the shell. That token also carries routing context — which block and which tab it belongs to — so the router knows where to send the command's responses without you specifying it.

If a terminal has no such token available (for example, very early in shell startup), wsh can instead fall back to talking over OSC escape sequences printed directly into the terminal stream; wavesrv and the terminal renderer recognize and strip these before displaying output. This path exists mainly as a bootstrap mechanism.

wsh on a remote host (SSH)​

When you connect to a remote host, wavesrv does not just open a shell over SSH — it also sets up a second channel dedicated to wsh so that remote blocks (editors, file previews, widgets) work the same way local ones do:

  1. wavesrv asks the SSH connection to forward a Unix domain socket back to itself (streamlocal-forward@openssh.com). This only works if the SSH server allows it; see Common failure points below.
  2. It checks whether a compatible wsh binary already exists on the remote host at ~/.termia/bin/wsh. If it's missing or out of date, wavesrv copies the correct binary for the remote OS/architecture into place and marks it executable — you may see a one-time prompt asking permission to do this, depending on your connection settings.
  3. wavesrv launches wsh connserver on the remote host over the same SSH session. This is a small long-lived helper, not a full copy of wavesrv — it just relays RPC traffic between the remote host and the socket opened in step 1.
  4. The connserver authenticates itself the same way local wsh does (a signed token, sent to it over SSH stdin rather than a network call), then the router registers it under a conn:<connection-name> route. From then on, anything you do in a block on that connection — opening a file, running wsh commands, previewing an image — travels over this same forwarded socket instead of spawning new SSH sessions.

If wsh cannot be installed or the socket cannot be forwarded, the connection still works as a plain SSH terminal; you simply lose the extra features that depend on wsh (file preview, remote editing, remote widgets, and the wsh CLI itself on that host).

Shell integration​

Whether local or remote, opening a new shell also loads a small startup script (written for the shell you use — bash, zsh, fish, or PowerShell). This script does a few things: it puts the platform's wsh binary on your PATH, sets sane UTF-8 locale defaults, emits the escape sequence that lets the app track your current working directory, and exchanges a short-lived one-time token (passed in via the TERMIA_SWAPTOKEN environment variable) for your real session's environment and any additional init script — this is how the terminal picks up things like per-connection environment variables without them being visible to other processes on the system.

Common failure points​

  • The SSH server blocks socket forwarding. If AllowStreamLocalForwarding (or the more general AllowTcpForwarding) is disabled on the remote sshd, wavesrv cannot open the forwarded socket described above. The SSH terminal session itself still works; only the wsh-dependent features are unavailable.
  • The remote wsh binary can't be installed or is outdated. If the copy step fails (no write permission, unsupported OS/architecture, or you declined the install prompt), wavesrv falls back to a plain SSH session.
  • A stale local wsh after an upgrade. The local binary in the app's data directory is kept in sync with the app version automatically; a remote host only gets a newer wsh pushed to it when it reconnects, since installation only happens once per connection.