Install & Pair a Node

Step-by-step — download the Node binary, pair it with your Gateway, approve in the Dashboard, and start it running.

Installing a Sophon Node takes four steps: register in the Dashboard, pair from the target machine, approve in the Dashboard, start the Node. Each step takes less than a minute once you know the commands.

Prerequisites

A running Sophon Gateway, reachable from the target machine (public URL, VPN, or tailnet).
Dashboard admin access — you need permission to manage nodes.
OS-specific CLI helpers (the installer prompts if they're missing):

OS	Install
Windows	Nothing extra — automation uses native P/Invoke
macOS	`brew install cliclick` (for mouse control)
Linux (X11)	`sudo apt install xdotool scrot xclip wmctrl`
Linux (Wayland)	`sudo apt install ydotool grim wl-clipboard`

Installation

The Node ships on NuGet as the package sophon-node and installs as a .NET global tool. It runs on Windows, macOS, and Linux and requires the .NET 10 runtime.

dotnet tool install -g sophon-node

To upgrade or remove it later:

dotnet tool update -g sophon-node      # upgrade to the latest version
dotnet tool uninstall -g sophon-node   # remove the tool

Verify the install:

sophon-node version

Don't want to install the .NET runtime? Self-contained, single-file builds (which bundle the runtime) are published for each platform — win-x64, win-arm64, osx-x64, osx-arm64, linux-x64, and linux-arm64. Download the build for your machine, unpack it, and put sophon-node on your PATH.

Four-step pairing

1. Register in the Dashboard

Settings → Devices → My Devices → Add Node.

Fill in:

Display name — something recognizable (e.g., "Office PC", "Home Mac mini")
Platform — Windows / macOS / Linux

Click Generate Pairing Credentials. The Dashboard shows:

A pairing code (three-letter/digit groups, for visual matching)
A ready-to-copy CLI command with the Node ID and secret pre-filled

Copy the command. The secret only appears once — if you close the dialog you'll have to regenerate.

2. Pair from the target machine

Paste the command you copied. It looks like:

sophon-node pair --gateway https://gw.example.com --node-id abc123 --secret s_a1b2c3d4...

The CLI polls the Gateway every 3 seconds waiting for approval:

Pairing with gateway at https://gw.example.com...
Waiting for approval (pairing code: ABC-123)...
Waiting for approval (pairing code: ABC-123)...

Keep this terminal open — the poll loop will pick up the approval in the next step.

3. Approve in the Dashboard

The Node now shows up in Settings → Devices as Pending with the pairing code. Verify the pairing code matches what your CLI is showing, then click Approve.

On the approval panel you can also configure:

Permission scopes — which command categories this Node can run (see Permissions & Scopes)
Label — change the display name if you picked something forgettable

Save. The CLI terminal shows:

Node paired successfully! Token saved to ~/.sophon-node/config.json

4. Start the Node

# Interactive mode — shows tray icon on Windows, console output on macOS/Linux
sophon-node start

# Headless service mode
sophon-node start --service

Expected output:

Sophon Node v1.0.0
Node ID:  abc123
Gateway:  https://gw.example.com
Connected to Gateway via SignalR.
Heartbeat sent. Status: Online.
Press Ctrl+C to stop.

Back in the Dashboard, the Node flips from Approved to Online with a green indicator.

Persisting the Node across reboots — for always-on Nodes, install as a system service. See Running as a Service.

Config file

Pairing writes the token to ~/.sophon-node/config.json:

{
  "gatewayUrl": "https://gw.example.com",
  "nodeToken": "abc123.a1b2c3d4e5f6..."
}

The token format is {nodeId}.{secret}. Only the SHA-256 hash of the secret is stored server-side.

Token storage is plaintext today. Anyone with read access to ~/.sophon-node/config.json can impersonate the Node. Restrict permissions to user-only (chmod 600 on Unix; default NTFS ACLs on Windows). OS-keyring storage (DPAPI / Keychain / libsecret) is on the roadmap.

Other CLI commands

# Status — shows pairing state, token prefix, Gateway URL, last heartbeat
sophon-node status

# Unpair — deletes config.json. Dashboard should also revoke.
sophon-node unpair

# Version — build info
sophon-node version

Troubleshooting

"Waiting for approval" forever — the Dashboard didn't receive the pair request. Check:

Gateway URL is correct (paste into a browser, you should see the Sophon welcome page or API root).
Pairing secret hasn't expired (they're valid for 15 minutes after generation).
Clock skew between Node and Gateway < 1 minute.

"Failed to connect to Gateway" — SignalR can't reach the hub. Check:

Firewall — the Node needs outbound HTTPS + WebSockets on port 443 (or whatever port the Gateway listens on).
TLS cert — if the Gateway uses a self-signed cert, you need to install it in the OS trust store (Windows: certutil, macOS: Keychain, Linux: update-ca-certificates).

"Node online but commands time out" — scopes probably aren't granted. In Settings → Devices → <node> → Permissions, enable the scope group you need and save.

macOS accessibility prompt — on first mouse/keyboard command, macOS asks for Accessibility permission for the Node process. Grant it in System Settings → Privacy & Security → Accessibility. Without this, cliclick can't drive the UI.

Linux Wayland limitations — ydotool requires a running user-level daemon. If commands fail silently, check systemctl --user status ydotool.service.

Where to go next

Permissions & Scopes — configure what this Node can do
Available Commands — the full command set and their parameters
Running as a Service — make the Node survive reboots

Install & Pair a Node

On this page