Install Watchflare Agent on macOS

Prerequisites: macOS 11 (Big Sur) or later, Intel or Apple Silicon, and Homebrew installed.

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 via Homebrew, registers it with the Hub, and starts the service in one step:

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

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

Manual install

Step 1 — Add the tap and install:

brew tap watchflare-io/watchflare
brew install watchflare-agent

Step 2 — Register:

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

Step 3 — Start the service:

brew services start watchflare-agent

Service management

brew services info watchflare-agent        # Status
brew services start watchflare-agent       # Start
brew services stop watchflare-agent        # Stop
brew services restart watchflare-agent     # Restart

Follow logs:

tail -f $(brew --prefix)/var/log/watchflare-agent.log

File locations

$(brew --prefix) is /opt/homebrew on Apple Silicon and /usr/local on Intel.

| Path | Purpose | |------|---------| | $(brew --prefix)/bin/watchflare-agent | Binary | | $(brew --prefix)/etc/watchflare/agent.conf | Config (credentials) | | $(brew --prefix)/etc/watchflare/ca.pem | Hub CA certificate | | $(brew --prefix)/var/watchflare/ | Data directory | | $(brew --prefix)/var/watchflare/metrics.wal | Write-Ahead Log | | $(brew --prefix)/var/watchflare/packages.state.json | Package inventory state | | $(brew --prefix)/var/log/watchflare-agent.log | Logs |

Re-registering

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

brew services stop watchflare-agent
rm $(brew --prefix)/etc/watchflare/agent.conf
rm $(brew --prefix)/etc/watchflare/ca.pem
watchflare-agent register --token wf_reg_YOUR_TOKEN --host YOUR_HUB_IP
brew services start watchflare-agent

Troubleshooting

| Symptom | Cause | Fix | |---------|-------|-----| | configuration error (config file not found) | Not registered | Run watchflare-agent register ... | | connection refused | Wrong host/port | Verify port 50051 is reachable | | Invalid agent credentials | Key mismatch | Re-register the agent | | Host stays offline after start | Clock desync | Check system clock — Hub rejects timestamps ±5 min off |

Check recent logs:

tail -50 $(brew --prefix)/var/log/watchflare-agent.log

Check service status:

brew services list | grep watchflare

Installing without Homebrew

If you cannot use Homebrew, the agent can be built from source — Go 1.22+ is required. Refer to the source repository for build instructions. Use the WATCHFLARE_CONFIG_DIR and WATCHFLARE_DATA_DIR environment variables to point the agent at custom paths, and start it manually or with your own service manager.