Troubleshooting

Troubleshooting

A host doesn't appear on the dashboard

• Check the agent is running: systemctl status autormm-agent (headless) or systemctl --user status autormm-agent (desktop).
• Check its logs: journalctl -u autormm-agent -f.
• Verify it can reach the hub: curl http://<hub-ip>:8765/healthz from the host.
• Confirm the enroll token matches the hub's.
• Firewall: the host must be able to reach the hub on its port (default 8765).

No graphs in the host detail view

Time-series graphs need the history database. It's on by default; if you started the hub with a custom setup, ensure --db <path> is set and writable. Sparklines and current values work without it — only the historical charts need it.

The "Remote" button is greyed out

That host has no graphical session to stream (it's headless, or the agent was installed as a system service instead of the &desktop=1 desktop variant). Screen sharing needs a desktop agent. Terminal, metrics, exec, and scripts still work.

Remote desktop is black / doesn't update

• Linux screen capture is X11-only — use Xorg or Xwayland, not native Wayland.
• The agent needs access to the X session (DISPLAY / XAUTHORITY); the desktop installer sets this up. Running the agent as a system service (no session) won't capture the screen.

Windows agent (system-tray app)

On v0.4.1+ the Windows install is a tray app that needs no admin — it starts at logon via a per-user registry Run key. If you don't see the tray icon after installing, check the log at %LOCALAPPDATA%\autormm\agent.log, or run it in the foreground to watch it connect:

& "$env:LOCALAPPDATA\autormm\autormm-agent-tray.exe" -server http://<hub-ip>:8765 -token <enroll>

Right-click the tray icon for Refresh status (reconnect now) and Update to latest (pull the current agent from the hub and restart). The agent also auto-updates at logon to match the hub's version, so hosts stay current without re-running the install command.

To remove it: delete the autormm-agent value under HKCU\Software\Microsoft\Windows\CurrentVersion\Run and end the autormm-agent-tray process (there is no Quit in the tray by design).

Older builds (≤ v0.4.0) used a scheduled task and could fail with Access is denied (0x80070005, needed an elevated PowerShell) or The parameter is incorrect (0x80070057, a bare-username bug). Update the hub to v0.4.1+ to switch to the no-admin tray installer.

No H.264 toggle in the remote viewer

The JPEG-tile / H.264 toggle only appears when both ends can do H.264:

• the host has ffmpeg (with libx264) on its PATH — install it, then restart the agent so it re-registers its capabilities;
• your browser supports WebCodecs — use Chrome or Edge.

If it's still JPEG-only, that's expected and harmless — JPEG-tile is the default and works everywhere. (If you pick H.264 and it can't decode, the viewer falls back to JPEG automatically.)

Terminal doesn't work on a Windows host

The Windows agent terminal isn't available yet (it needs ConPTY). Use the browser/CLI terminal on Linux/macOS hosts; on Windows, use exec for one-off commands.

Can't reach the dashboard from another machine

• Confirm the hub is bound to a reachable address (-addr 0.0.0.0:8765, not 127.0.0.1).
• From outside your LAN, you need a zero-trust overlay or VPN — see Remote Access. Don't port-forward it to the internet.

Resetting the admin token

Stop the hub, edit ~/.config/autormm/autormm.json (or the env file), and restart. Agents keep working as long as the enroll token is unchanged.