Desktop node setup
Make your desktop machine a node through Subshell Client.
Before you start
Follow Install Subshell Client, then open Settings → Nodes in the server dashboard's sidebar and select Add node at the top of the page. Choose a reachable address, generate a setup key, and select Desktop App to find the enrollment values.

The client has a dashboard window and a separate node-management window. Local node operations belong to the node window.
If Subshell Client is already configured only to watch sessions, open its local window using Window → Open Client App or the tray's Open Client App item. Choose Service in that window's sidebar and select Register this machine, following any node-installation prompts first.
Enroll
- Open Subshell Client and choose Run subshells on this machine. If its dashboard is already open, choose Window → Open Client App in the app's menu bar, or Open Client App in its tray menu to open the local node window.
- Enter the server address and setup key.
- Choose a recognizable machine name.
- Follow the tmux and service instructions.
- Verify that the node appears online in the server's node list.
The client bundles the node binary. It can enroll even when the control plane has no downloadable node binary staged locally, provided the bundled version is compatible.
Configure local execution
Install coding agent CLIs under the node's OS account. Set Directory restrictions and confirm the appropriate persistence mode before leaving a task running.
Agents run on the node. The server stores your instance settings and serves the dashboard.
Run graphical apps on this machine
Follow Preview prerequisites and setup to enable web previews or virtual displays on the enrolled node. For a Mac, follow macOS virtual displays to open Virtual Displays in the local node window, enable the helper, and grant macOS permissions. For a Linux machine, follow Linux virtual displays.
Re-register an existing node
Use re-registration to recover a machine's connection while keeping its existing node entry, name, shares, settings, and session records. The node's owner can press it, and a server admin can too.
- In the server dashboard, open Nodes, select the existing node, and press Re-register on its Overview page.
- In Generate a new setup key?, select Generate setup key. Copy the server address and setup key from the Desktop App instructions.
- On the machine, open Subshell Client's local window, choose Service, and select Re-enroll…. If the machine has lost its configuration, use the registration flow instead.
- Enter that server address and setup key, supply the requested machine name, and finish registration. The server keeps the existing node name.
- Verify that the same node entry returns online.
Generating the key leaves the current connection working. Using it replaces the credentials and disconnects the previous connection. The key is single-use and expires after 24 hours. An ordinary Add node setup key creates a new node entry; use the key generated from the existing node's Re-register control for recovery.
Removal
In Subshell Client's local node-management window, select Reset in its sidebar and review the deletion plan before confirming. This is separate from resetting the remote server. Read Unenroll a node first.
Next steps
Launch a subshell on the new node.
Edit on GitHubLast updated on
