Turn a desktop into a node

Turn the desktop machine you are sitting at into a node from the Subshell Client app, without a terminal.

Subshell Client is two things in one app: your interface to a control plane, and the place where the machine you are sitting at becomes a node. The second half lives in a separate window, opened by the app's own Open Client App item (the tray on every platform, the Window menu on macOS). It registers this machine: you paste a setup key and name the machine, and it installs the node binary, enrols it, and gets it running in the background. There is no terminal and no download step, because the binary ships inside the app. The unpublished-binary warning and the air-gapped detour are concerns of the terminal path; the app carries its own copy whatever this server has published.

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 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, and you do not enroll that one here. This window registers the machine Subshell Client runs on, with whichever control plane you point it at.

Before you start

On the control plane, open the Nodes page, press Add node, and mint a setup key. The dialog's reveal switches from Terminal to Desktop App and shows two values instead of a command: the server address and the setup key, each with its own copy button. Both are pasted into the app at step three below. Add a node covers what a key is and how long it lives, and the key stays listed on the Nodes page until it is used.

The assistant screen by screen

The assistant asks one question per screen, and it asks what you came for before it touches your machine. A machine with nothing set up starts at Welcome to Subshell Client, a single sentence and a Continue button that runs nothing.

What Would You Like to Do?: the walk's one fork, answered by pressing one of two options. Run subshells on this machine registers this machine as a node, so agent sessions can run here. Connect to a server opens a Subshell server's dashboard and touches nothing: nothing is installed or registered. Whichever you pick, the other is still available afterwards.
Install tmux: the node path's gate, shown while the machine has no tmux. Every subshell runs in a tmux pane, and a tmux-less node would come up online and then fail every launch, so there is no skip. The screen offers Install tmux, which runs your platform's package manager, and it prints the same command for a terminal; your package manager may ask for your password, and a failed install relabels the button Try again. The screen leaves on its own as soon as tmux appears, because the app re-reads the machine on its own. Back is a different offer: it leaves the walk, and the watch path is still available.
Register This Machine: you fill in the two values the plane's Nodes → Add node dialog shows on its Desktop App path, a Server URL and a single-use Setup key, and a Node name, which is required: naming moved off the control plane and onto the machine being named. The screen's Continue button checks the answers' shape and spends nothing, and the press that spends the key is one screen later.
How This Node Runs: the node always runs as a background service, as a systemd user unit on Linux or a launchd agent on macOS, so the only question is Start at login, and it defaults to on. Register is the press that acts: it installs the node, enrols this machine, and installs the service.
Setting Up…: the checklist that press runs, in order: Install the Subshell Node CLI, Enroll this machine, Start the node service. 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; a binary too old for that is replaced with a plain copy, and the app says plainly that no rollback point was recorded. 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. A row that fails shows the command's own words and offers Retry, or Edit details while the key is still unspent; when every row is done, Continue moves on.

The watch path

The watch path is one screen: Connect to a Server, where you enter the address of the Subshell server this app should show. Connecting registers and installs nothing on this machine and opens nothing itself; the address joins the Control Plane list, and its dashboard is the row's to open.

After the walk

Both paths end at the same standing sections, and a set-up app opens on Control Plane, which lists the addresses it can connect to. Pressing one opens that plane's dashboard in the app, and the row's menu adds Open in dashboard, Open in browser, and Copy URL. The address this machine's node reports to is in the list too, pinned as its first row. The rail then carries Status, which says what this machine is and shows the node's log, Service, the node's own machinery, Update, and About. Doing step 3 again deliberately is the Re-enroll… act, offered on the Service section's Enrolled to Control Plane card beside the plane's address, and it runs this same walk seeded with that address.

Enrolling twice is destructive

A second enrollment overwrites the node's saved configuration, registers a second node on the control plane, and discards the current node key, whose only home was that overwritten file. The app will not run an enroll until you confirm exactly that. If you are already enrolled and only need to reach a plane that moved to a different address, that is repointing (Manage a node), which keeps the machine's identity and mints nothing.

Taking the node back out

The window can also take the node back out. The rail's Reset item opens a Reset everything? dialog that removes the node's service and its enrollment, and you type this machine's name to confirm. The control plane keeps a node row for the machine, and it shows as permanently offline until its owner deletes it there.

The Service section carries the node's lifecycle: Start, Stop, Restart, Uninstall, and Un-enroll…, the destructive ones confirmed in their own words. Restart is the act that can take subshells down, so its two-phase confirmation reads the CLI's pane-safety refusal aloud before a forced restart is offered. Control Plane opens the plane in your real browser, for anything a webview is wrong for, such as sharing a subshell or using passkeys.

Other pages

Add a node: the same enrollment from a terminal, one command.
Manage a node: service controls, logs, and repointing from the browser.
Nodes overview: what registering this machine actually delegates.

Edit on GitHub