Install & Pair a Node

Install the node binary, pair it with your gateway, approve it, and start it, plus the config file and the five CLI verbs.

Four steps, each under a minute: install the binary, pair it with your Gateway, approve the pairing in the Dashboard, and start it.

A node needs a real desktop session to drive, so install it on the machine you actually want operated, not on a server.

Prerequisites

Platform	What it needs
Windows	Nothing extra. Input, capture, and element queries use the platform's own APIs.
macOS	Accessibility permission for the node, or the OS refuses input and element queries. Some input needs a helper utility installed.
Linux	Helper utilities for input, capture, and clipboard. Which ones depends on X11 versus Wayland. A missing tool produces an error naming what to install.

On Linux the node probes for those helper tools and reports what it found with its heartbeat, so a half-provisioned machine is visible in the Dashboard rather than failing mysteriously later. Windows and macOS have nothing to probe yet, so check the macOS Accessibility grant yourself.

Install

As a .NET global tool, if the machine already has the .NET 10 runtime:

dotnet tool install -g sophon-node

# Later
dotnet tool update -g sophon-node
dotnet tool uninstall -g sophon-node

Or take a self-contained build from /downloads/node, which bundles the runtime so the machine needs nothing preinstalled. Builds are published for win-x64, osx-arm64, and linux-x64 — the three the release pipeline produces.

Node binaries are not code-signed. Windows and macOS will flag them as coming from an unidentified developer. Check what you downloaded before you run it, and see Platform Support & Limits for what else this release does not include.

Pair the node

1. Register in the Dashboard

Go to Devices → Add device → Pair a Sophon Node, give it a name you will recognise later, and copy the pairing command it hands you. Node names matter: a run is pinned to whichever node it resolves, and an agent routing work to the wrong machine is a configuration problem you want to spot by reading the name.

2. Pair from the target machine

sophon-node pair --gateway https://gw.example.com --node-id <ID> --secret <SECRET>

All three options are required. The command polls the Gateway every few seconds and waits for you to approve it.

3. Approve in the Dashboard

The device appears as Pending. Approve it, and review its scopes: it starts with eight, and the ones that reach past the screen, meaning shell, files, activity history and voice, are deliberately not among them. See Permissions & Scopes.

activity.read is the one that surprises people. It is not granted on approval, and without it the Dashboard's own Activity history settings panel and the Activity timeline for that device do not work either — they reach the node over the same scope an agent would. Grant it only if you want that record kept and readable.

4. Start it

sophon-node start            # with a console
sophon-node start --service  # no console, for a service manager

The node connects, begins heartbeating every 30 seconds, and is ready. To keep it running across reboots, see Running as a Service.

Configuration file

The node keeps its state in config.json under its own directory in your home folder.

Key	Purpose
`gatewayUrl`	The paired Gateway
`nodeToken`	The node's credential
`consentRequiredCommands`	Command types that must ask on the device before running. Defaults to shell execution and Canvas. See the consent prompt
`fileSystemRoots`	Folders `filesystem.*` may touch. See File Access
`activityRecording`	Background activity recording, off by default, including the separate screenshot opt-in. See Desktop Awareness

Only activityRecording has a second home: the same settings are in the Dashboard at Devices → (device) → Settings → Activity history, which is the easier place to reach them, and changes made there take effect without restarting the node.

Key names are case-sensitive, and fileSystemRoots has a capital S. A key the node does not recognise is ignored silently rather than reported, so a misspelling does not error. It leaves the setting at its default. That matters most for this one: writing filesystemRoots: [] intending to switch file access off would leave the default roots in place instead. Check sophon-node status after editing.

The token is stored in plain text. Keep the file readable only by the account that runs the node: chmod 600 on macOS and Linux, and the equivalent ACL on Windows. OS keyring storage is planned.

The node also writes rolling daily logs beside its config, keeping a couple of weeks of them. See Logs.

CLI reference

The node binary has five verbs. That is the whole surface.

Verb	What it does
`pair`	Pairs with a Gateway. Requires `--gateway`, `--node-id`, `--secret`
`start`	Runs the node. `--service` omits the console
`status`	Pairing state, Gateway URL, and last heartbeat
`unpair`	Clears local pairing state
`version`	Prints the version

There is no doctor, install, or uninstall verb. Those were proposed and withdrawn. Note also that sophon nodes … is a different program: that is the Gateway CLI for managing nodes from elsewhere, documented in CLI commands. This page is about sophon-node …, the binary that runs on the machine.

Troubleshooting

Pairing never completes. The node polls until approved, so check the Dashboard for a Pending device. If nothing appears, the --node-id or --secret does not match the registration.

Node shows Offline. It is offline after two minutes without a heartbeat. Check the process is running, and that the machine can reach the Gateway URL outbound. Nothing needs to be open inbound.

Commands are refused. Check the scope first, because a refusal at the scope gate never reaches the machine. Then check whether the command is consent-gated and the prompt was missed; it times out after 15 seconds and fails closed.

The Dashboard's Activity history panel or timeline will not load. The device does not hold activity.read. It has no checkbox of its own: add it under Devices → (device) → Settings → Permission scopes → Advanced: custom scopes, and save. It takes effect without a restart.

Input or element queries do nothing on macOS. Accessibility permission has not been granted, or was reset by an update.

Input fails on Linux. A helper tool is missing, and the error names it. Wayland and X11 need different ones.

Where to go next

Running as a Service — surviving a reboot, and why it runs as you
Permissions & Scopes — what to grant after approving
Control Runs — how the agent actually drives it
Platform Support & Limits — what your OS supports

Install & Pair a Node

On this page