Onboarding Hosts

Onboarding Hosts

Adding a machine is one copy-paste. The hub serves the agent binary itself, so there's nothing to download by hand and no tokens to copy around.

The easy way — "Add host"

1. In the dashboard, click ＋ Add host (top bar).
2. Copy the one-liner for the machine's OS.
3. Run it on that machine.

The commands come pre-filled with your hub's address and enroll token:

Linux — server / headless

curl -fsSL "http://<hub-ip>:8765/install.sh?token=<enroll>" | sudo sh

Linux — desktop (adds screen sharing; no sudo — runs in your session)

curl -fsSL "http://<hub-ip>:8765/install.sh?token=<enroll>&desktop=1" | sh

Windows — run in a normal PowerShell (no admin needed), signed in as the user who sits at the console:

iwr -useb "http://<hub-ip>:8765/install.ps1?token=<enroll>" | iex

On Windows this installs a small system-tray app: a status icon (● connected to the hub / ○ disconnected) that starts automatically at every logon via a per-user registry Run key — no admin, no scheduled task. On Linux the script installs a systemd service. Either way the host appears on the dashboard within a few seconds.

Windows: elevated actions (optional)

The Windows tray agent runs as the logged-in user, so it can't stop system services, install Windows Updates, or run admin commands. To enable those, install the elevated helper — a one-time step in an administrator PowerShell (copy the command from Add host → Windows elevated helper):

iwr -useb "http://<hub-ip>:8765/install-elevated.ps1?token=<enroll>" | iex

It installs a small LocalSystem Windows service alongside the tray. The hub then routes privileged work (service control, elevated commands) through it as SYSTEM, while the tray keeps doing screen/input/terminal. The host detail panel shows Admin helper: installed ✓ once it's attached.

Headless vs. desktop

	Headless / server	Desktop
Install	sudo sh (system service)	&desktop=1, no sudo (user session)
Metrics, terminal, exec, scripts	✅	✅
Screen sharing (Remote)	❌ (no display)	✅

A headless host shows up as monitor-only — the Remote button is disabled because there's no graphical session to stream.

Keeping hosts up to date

Agents auto-update to match the hub — on Windows via the tray, on Linux via the systemd service (it downloads the new binary and exits; systemd relaunches it). Each update is validated first: the downloaded binary must be the right size, a real executable, and report the hub's exact version when run, or it's rejected and the current agent keeps running.

Update the whole fleet from the dashboard: click the ⟳ button in the top bar → Check for updates. If a newer hub release exists, Update hub downloads it from GitHub, verifies its checksum + smoke-tests it, then swaps and restarts. Push update to all hosts tells every online agent to check and update immediately (instead of waiting for their periodic check). Agents also follow on their own within a few hours, or force one from the Windows tray → Update to latest.

Manual install

If you'd rather not pipe a script, grab the agent from a release (or /download/agent) and run it directly:

autormm-agent --server http://<hub-ip>:8765 --token <enroll> --tags web,prod

Handy flags: --id (stable name, defaults to hostname), --tags, --allow-exec=false (disable remote command/terminal on this host), --insecure (skip TLS verify for self-signed certs).

Turning a host off

Stop and remove the agent service on the host:

sudo systemctl disable --now autormm-agent      # headless
systemctl --user disable --now autormm-agent    # desktop

It will show as offline on the dashboard.