Skip to content

Verify & Troubleshoot the Agent

Quick checks

  • Service: systemctl status clipal-agent (should be active)
  • Logs: journalctl -u clipal-agent -n 50 or -f to follow
  • Network: allow outbound 443/WSS to docs.clipal.me/app domain
  • Time sync: ensure NTP is running to avoid token expiry issues

Common issues

  • Offline in dashboard: service not running, firewall egress blocked, or invalid/expired token. Re-run with a fresh token if needed.
  • Terminal fails to open: re-login to refresh your session; ensure browser allows WSS; check agent logs for auth errors.
  • Metrics missing: agent running but cannot send metrics; check outbound connectivity and disk space; ensure system clock is correct.
  • Permission errors: run install as a sudo-capable user; ensure /opt/clipal (or install path) is writable during install.
  • psutil warning: Install with pip3 install psutil. System monitoring is disabled without it.
  • MySQL metrics not appearing: Check config file at /opt/clipal/clipal.conf has mysql_enabled=true and correct credentials. Requires paid plan.
  • MySQL connection errors: Verify MySQL user has PROCESS privilege and SELECT on performance_schema.*. Check logs with journalctl -u clipal-agent -f.
  • Config file not found: Run the install script again with a valid token. The config file is created at /opt/clipal/clipal.conf during installation.

When reinstalling

  1. Stop service: sudo systemctl stop clipal-agent
  2. Remove old service/files per uninstall notes
  3. Generate a new token in the dashboard
  4. Run the fresh install command