Install on Linux

Prerequisites: A Linux host with systemd, curl or wget, and sudo access. Tested on Ubuntu 18.04+, Debian 10+, RHEL/CentOS 7+, Fedora 30+, Amazon Linux 2+, Arch Linux.

Before starting, create the host in the Watchflare dashboard (Hosts → Add host) and copy the registration token.

One-command install (recommended)

This installs the agent, registers it with the Hub, and starts the systemd service in one step:

curl -sSL https://get.watchflare.io | sudo bash -s -- \
  --token wf_reg_YOUR_TOKEN \
  --host YOUR_HUB_IP \
  --port 50051

Replace YOUR_HUB_IP with the IP or hostname of your Hub and wf_reg_YOUR_TOKEN with the full token copied from the dashboard.

The installer:

1. Checks permissions (requires root)
2. Creates the watchflare system user
3. Creates data and config directories
4. Copies the binary to /usr/local/bin/
5. Installs the systemd service
6. Registers the agent with the Hub
7. Enables and starts the service

=== Watchflare Agent Installation ===

[1/7] Checking permissions...
→ Running as root
[2/7] Creating system user...
→ Created user 'watchflare'
[3/7] Creating directories...
[4/7] Installing binary...
[5/7] Installing service...
[6/7] Agent registration...
→ Registering agent with Hub...
→ Registration successful
[7/7] Starting service...
→ Service started successfully

=== Installation Complete ===

The host transitions from pending to online in the dashboard within 5 seconds.

Two-step install

If you want to install the binary first and register later:

Step 1 — Install without registering:

curl -sSL https://get.watchflare.io | sudo bash

Step 2 — Register when ready:

sudo watchflare-agent register \
  --token wf_reg_YOUR_TOKEN \
  --host YOUR_HUB_IP \
  --port 50051

Step 3 — Enable and start the service:

sudo systemctl enable --now watchflare-agent

Service management

sudo systemctl status watchflare-agent     # Status
sudo systemctl start watchflare-agent      # Start
sudo systemctl stop watchflare-agent       # Stop
sudo systemctl restart watchflare-agent    # Restart
sudo systemctl enable watchflare-agent     # Enable at boot
sudo systemctl disable watchflare-agent    # Disable at boot
journalctl -u watchflare-agent -f          # Follow logs

File locations

Re-registering

To connect the agent to a different Hub or after deleting and recreating a host:

sudo systemctl stop watchflare-agent
sudo rm /etc/watchflare/agent.conf /etc/watchflare/ca.pem
sudo watchflare-agent register --token wf_reg_YOUR_TOKEN --host YOUR_HUB_IP
sudo systemctl start watchflare-agent

SELinux

On RHEL, CentOS, and Fedora, restore SELinux contexts after installation:

sudo restorecon -Rv /usr/local/bin/watchflare-agent
sudo restorecon -Rv /etc/watchflare
sudo restorecon -Rv /var/lib/watchflare

Troubleshooting

Check the logs for details:

journalctl -u watchflare-agent -n 50
# or
tail -50 /var/log/watchflare-agent.log

A healthy agent produces log lines like these on startup:

2026/01/02 15:04:05 INFO   Watchflare Agent starting  version=v0.33.1
2026/01/02 15:04:05 INFO   environment detected  type="Physical Host"
2026/01/02 15:04:05 INFO   heartbeat started  interval_sec=5
2026/01/02 15:04:05 INFO   package collector started
2026/01/02 15:04:05 INFO   waiting before initial package collection  delay_sec=60

Common error patterns:

2026/01/02 15:04:05 WARN   heartbeat failed  error="Heartbeat failed: dial tcp 1.2.3.4:50051: connect: connection refused"
2026/01/02 15:04:05 WARN   heartbeat failed  error="Heartbeat failed: rpc error: code = Unauthenticated desc = Invalid agent credentials"
2026/01/02 15:04:05 ERROR  send failed: clock out of sync with backend