Troubleshooting

Logs

journalctl -u fleetd-server -f      # server
journalctl -u fleetd-agent -f       # agent on systemd
logread -f -e fleetd                # agent on OpenWrt

A new machine does not appear

Check the agent log. handshake (wrong server key?) means server_key in the agent config does not match the server; copy it from Settings → Server.
rejected by the admin means the machine was rejected; unblock it in Settings → Rejected machines.
too many machines waiting for approval: approve or reject the pending ones first.
Check that the machine reaches the server: curl -I https://fleetd.example.com/login.

A machine was approved but shows no data

Waiting agents retry once a minute, so data can take up to a minute after approval.

Machines go offline every few minutes

Usually a reverse proxy closing idle WebSockets. Raise its read and send timeouts (for nginx, proxy_read_timeout 3600s). The server pings every 30 seconds, so anything above a minute works.

Too many failed sign-ins: five failures lock the username and IP for 15 minutes. Restarting the server also clears it.
Forgot the password: fleetd-server -config /etc/fleetd/server.yaml admin-add <user> resets it.
Signed in but immediately sent back to the login page: over plain HTTP the session cookie is not Secure, but some browsers still drop it on non-localhost addresses. Use HTTPS.

A command is rejected

The result says why:

Message	Fix
`signer is not in trusted_signers`	Add your browser's public key to the agent's `trusted_signers`
`commands are disabled on this machine (permission: monitor)`	Raise `permission` in the agent config
`arbitrary commands require permission: full`	Use `full`, or define an allowlist action
`command expired` / `issued in the future`	The machine's clock is off by more than 2 minutes; fix NTP
`This browser has no signing key yet`	Create one in Settings → Signing keys

An agent update fails

The reason is under Alerts → History:

release signature invalid: the agent's release_key is not the key that signed the build.
release … is not newer than …: build with a higher VERSION.
updates disabled: release_key not set: add release_key to the agent config, or reinstall with the one-line installer.

The install script fails

no amd64 release uploaded on the server?: upload an agent build in Settings → Agent releases.
needs systemd or OpenWrt procd: other init systems are not supported; run the agent with your own service manager.
run as root: use sudo sh -s -- … after the pipe, e.g. curl -fsSL … | sudo sh -s -- --permission full.