Subshell Client as a Node

Subshell Client is two things in one app: your interface to a control plane, and the place where this machine becomes a node. The second half lives in a separate window, Window → This machine…, an assistant that walks you through registering the machine you are sitting at: paste a setup key, name the machine, and it installs the node binary, enrols it, and gets it running in the background. No terminal, no download step: the binary ships inside the app.

Who needs this window

If you launch subshells on the same machine you watch them from, which is most people, this is the easy path, and it is the one the desktop install puts you on. If you only ever watch subshells that run somewhere else, you never need to open this window at all. Its existence is the entire "node functionality" toggle: there is no mode to set, and an app that never opened it is a pure client.

The machine hosting the control plane has its own built-in node row; you do not enroll that one here. This window registers the machine Client runs on with whichever control plane you point it at.

The assistant, screen by screen

One question per screen, in order:

1. Connect: the control plane's address, entered first because everything else is an answer about a plane nobody has named yet. This is the address the app's other window loads.
2. Install the node: the bundled binary is installed to ~/.local/bin/subshell, the same managed copy the command-line path writes, so one machine cannot end up with two of them. Replacing an existing binary goes through the node's own update transaction, which records a rollback point; if the installed binary is too old to have one, the screen says so plainly instead of pretending.
3. Enroll: you paste the two values the plane's Nodes → Add node dialog shows on its Desktop App path: the server address and a single-use setup key (Adding a Node covers what a key is and how long it lives, and it stays listed on the Nodes page until it is used). The screen also asks a Node name, and it is required: naming moved off the control plane and onto the machine that knows what it is. The node generates its identity on this machine and consumes the setup key in the exchange: it keeps no copy of the key, which lives 24 hours at most; the long-lived node key the exchange returns is stored only in the node's private 0600 config file, its one home.
4. Service: the app offers to start the node at login and keep it running (a systemd user unit on Linux, a launchd agent on macOS).
5. Connected: the node's live state, whether it is online, what the service manager says, and a Re-enroll… entry point for deliberately doing step 3 again.

tmux is a gate, not a caption: while the machine has no tmux, the enroll and service buttons stay disabled, because a tmux-less node would come up online and then fail every launch. The screen names the install command for your platform; installing it and pressing Refresh re-arms the buttons.

The window can also take the node back out (reset removes the service and the enrollment), and it can open the control plane in your real browser for anything a webview is wrong for, like sharing a subshell or using passkeys. Stopping or uninstalling the node from here is deliberately not offered: both would end the very connection their own undo would ride, and that call belongs to the node's page. Restart is the one the assistant keeps (an offline node can only be revived at the machine it sits on), and its confirmation names which subshells it will take down.

See also

• Adding a Node: the same enrollment from a terminal, one command.
• Managing a Node: service controls, logs, and repointing from the browser.
• What a Node Is: what registering this machine actually delegates.

Edit on GitHub