How to put a machine under remote support, on macOS, Windows and Linux — what to install, what the one-command installer actually does, and how to keep it running.
Every registered machine needs two things: a VNC server serving its screen on 127.0.0.1:5900, and the agent, which dials out to this hub and forwards that port over an authenticated WebSocket. The agent is what makes NAT and firewalls stop mattering — nothing inbound is ever opened on the machine.
You also need an enrollment link. In the console, open Machines → Invite a machine. The link carries a one-time token and expires; open it on the machine being registered and it shows the exact command with the token already filled in.
System Settings → General → Sharing → Screen Sharing. Under Computer Settings, enable VNC viewers may control screen with password and set a password — the hub authenticates with it and never passes it to the browser.
macOS serves VNC on port 5900 on all interfaces. The agent only ever connects to it over loopback, so you can firewall the port off from the network.
brew install node, or the installer from nodejs.org. Check with node -v.
Paste this in Terminal, replacing TOKEN with the one from your enrollment link:
It installs to ~/.rcs-agent, enrolls the machine, and loads a launchd agent so it starts at login and restarts if it dies.
| Do this | Command |
|---|---|
| Stop | launchctl unload ~/Library/LaunchAgents/com.freakma.rcs-agent.plist |
| Start | launchctl load ~/Library/LaunchAgents/com.freakma.rcs-agent.plist |
| Watch the log | tail -f ~/.rcs-agent/agent.log |
| Remove | launchctl unload …plist && rm -rf ~/.rcs-agent |
Windows has none built in. TightVNC or UltraVNC both work. During setup, register it as a system service so it survives reboots, and set a password.
In PowerShell, with TOKEN from your enrollment link:
No prerequisites. If Node.js 22+ happens to be installed the script uses it; otherwise it downloads rcs-agent.exe, a self-contained build with its own runtime inside. Everything lands in %LOCALAPPDATA%\RemoteControlSupport and no administrator rights are needed.
Those ship PowerShell 2.0, which has no irm, and .NET 3.5, which does not negotiate TLS 1.2 by default — the short command fails on both counts. Use this instead, from cmd.exe:
If it still cannot connect, the machine is missing KB3154518, which adds TLS 1.2 to .NET 3.5. As a last resort, download the agent on another machine, copy it across, and run rcs-agent.exe enroll <link> then rcs-agent.exe run.
| Do this | Command |
|---|---|
| Check it exists | schtasks /query /tn RemoteControlSupportAgent |
| Start | schtasks /run /tn RemoteControlSupportAgent |
| Stop | schtasks /end /tn RemoteControlSupportAgent |
| Remove | schtasks /delete /tn RemoteControlSupportAgent /f |
For an existing X session — what you want for support, since it shows the real screen:
On Wayland, x11vnc cannot see the screen. Either log in on an Xorg session, or use a Wayland-native server such as wayvnc.
| Distro | Command |
|---|---|
| Debian / Ubuntu | curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt install -y nodejs |
| Fedora / RHEL | sudo dnf install nodejs |
| Arch | sudo pacman -S nodejs |
It installs to ~/.rcs-agent and registers a systemd user service. It also enables lingering, so the agent keeps running when nobody is logged in — without that, the machine drops off the console at logout, which is exactly when you tend to need it.
| Do this | Command |
|---|---|
| Status | systemctl --user status rcs-agent |
| Logs | journalctl --user -u rcs-agent -f |
| Restart | systemctl --user restart rcs-agent |
| Remove | systemctl --user disable --now rcs-agent && rm -rf ~/.rcs-agent |
Printers, appliances, locked-down boxes, anything too old for a current runtime — the agent does not have to run on the machine it serves. Run it on any other machine on the same LAN and point it across:
That host now needs to reach the target's VNC port, and it becomes the machine whose uptime determines whether the target is reachable.
| Symptom | Cause |
|---|---|
| timed out connecting to …:5900 | This hub cannot route to that address. A direct-mode entry on a subnet the hub cannot reach — register it with the agent instead. |
| cannot reach …:5900 (ECONNREFUSED) | Routing is fine, nothing is listening. The VNC server is not running. |
| VNC authentication failed | Wrong stored password. Note that VNC authentication only uses the first 8 characters. |
| Enrollment says the link expired | Enrollment tokens are one-time and time-limited. Mint a new one. |
| Machine shows offline right after install | The agent is not running. Check the service commands for your platform above. |
| Sessions hang on "waiting for consent" | Ask first is on and the agent cannot show a dialog — it is running headless, as a Windows service, or on Linux without zenity/kdialog. |
Both scripts are served by this hub with its address and your token already substituted in, so there is nothing to fill in. They are worth reading before you pipe them into a shell — install.sh and install.ps1 are the exact text that runs. In order they:
Access control, support links and session policy are covered in the project README.