Skip to content

Install the Agent

The CLI Pal agent is a lightweight Python service that opens a secure outbound WebSocket connection to the platform—no inbound ports or stored SSH keys.

Get your token

  1. In the dashboard, add a new server.
  2. Click Generate install token. Tokens are short-lived and single-use.

Run the install command

  1. SSH into the target server with a sudo-capable user.
  2. Copy the one-line install command from the UI (it embeds your token).
  3. Run it; it will:
  4. Download and place the agent
  5. Create a systemd service
  6. Start the service and connect over WSS

Verify the service

  • systemctl status clipal-agent shows active (running).
  • journalctl -u clipal-agent -f streams agent logs.
  • In the web app, the server status switches to Online and metrics appear.

MySQL configuration

To enable MySQL monitoring (paid plans only), edit /opt/clipal/clipal.conf:

# Required: MySQL connection
mysql_enabled=true
mysql_host=localhost
mysql_port=3306
mysql_user=your_mysql_user
mysql_password=your_mysql_password

# Optional: Read credentials from my.cnf instead
mysql_cnf_file=/etc/mysql/my.cnf

# Optional: Slow query threshold (default: 200ms)
mysql_slow_threshold_ms=200

After editing the config, restart the agent: 

sudo systemctl restart clipal-agent

MySQL user permissions

The MySQL user needs these permissions for query analysis: 

GRANT SELECT ON performance_schema.* TO 'clipal_user'@'localhost';
GRANT PROCESS ON *.* TO 'clipal_user'@'localhost';
FLUSH PRIVILEGES;

Dependencies

The agent requires: - psutil (required for system metrics): pip3 install psutil - mysql-connector (required for MySQL features): pip3 install mysql-connector-python

The install script attempts to install these automatically.

Configuration file reference

Location: /opt/clipal/clipal.conf

All available options: 

# Required
api_key=<your_token>
server_url=wss://app.clipal.me/ws

# MySQL monitoring (optional, paid plans only)
mysql_enabled=true|false
mysql_host=localhost
mysql_port=3306
mysql_user=<username>
mysql_password=<password>
mysql_cnf_file=<path>  # Alternative to user/password
mysql_slow_threshold_ms=200  # Minimum query time to track

Uninstall or rotate

  • Stop and disable: sudo systemctl stop clipal-agent && sudo systemctl disable clipal-agent
  • Remove service/files per the uninstall instructions in the UI.
  • If a token is compromised, generate a new one and reinstall.