Skip to content
VordFleet

Agent Troubleshooting

Last updated: 2026-10-07

If your VordFleet agent is not reporting correctly, use these steps to diagnose and fix the issue.

Agent Not Appearing in Dashboard

  1. Check the service is running:
sudo systemctl status vord-agent

  1. Verify the registration token is correct in /etc/framlux/vord-agent.toml.

  2. Check network connectivity — the agent needs outbound HTTPS access to grpc.app.vordfleet.dev on port 443.

  3. Review the logs:

sudo journalctl -u vord-agent --no-pager -n 100

Agent Showing as Offline

If the agent was previously connected but now shows offline:

  • Check if the host rebooted — the agent should restart automatically via systemd.
  • Check disk space — if the root partition is full, the agent may fail to write its state file.
  • Check DNS resolution — ensure grpc.app.vordfleet.dev resolves correctly.

Updating the Agent

To update to the latest agent version:

curl -fsSL https://get.vordfleet.dev | sudo bash -s -- --update

This upgrades the installed vord-agent package through your system’s package manager and restarts the service. It does not need a registration token.

Uninstalling the Agent

To remove the agent completely:

sudo systemctl stop vord-agent
sudo systemctl disable vord-agent
sudo apt remove vord-agent    # Debian/Ubuntu
sudo dnf remove vord-agent    # RHEL/Fedora

The host appears as offline (or Paused, if it is over your plan’s host limit) in the dashboard. Tenant admins and machine admins can remove it with the Remove host button in the Remove host section of the Overview tab on the host’s detail page.

Reinstalling the agent when you’re over your host limit

Reinstalling the agent on a host means removing it and registering it again. If your fleet is over its plan’s host limit, removing an active host lets the oldest paused host take its slot, and the reinstalled host is then refused, because registration needs room under the limit. Remove paused hosts you no longer need, or upgrade, before reinstalling.

Updating the agent with --update doesn’t remove or re-register the host, so it never costs a slot.

← Back to Support