H

Troubleshooting

Solutions for common issues with the HelmRelay agent and dashboard.

Agent won't start

Check the service status and logs:

sudo systemctl status helmrelay-agent
sudo journalctl -u helmrelay-agent -n 50 --no-pager

Common causes:

  • Invalid token — verify the token in /etc/helmrelay/agent.yaml matches your dashboard
  • Port blocked — ensure outbound port 443 is open: curl -I https://api.helmrelay.com
  • Permission denied — the service should run as root or a user with appropriate permissions
  • Binary missing — check if /usr/local/bin/helmrelay-agent exists

Server shows "Disconnected"

  1. SSH into the server
  2. Check if the agent is running: systemctl is-active helmrelay-agent
  3. If not running, start it: sudo systemctl start helmrelay-agent
  4. Check logs for errors: journalctl -u helmrelay-agent -n 20
  5. Test outbound connectivity: curl -I https://api.helmrelay.com

Commands not executing

  • Check your plan — AI commands require Starter or higher. See plans
  • Server selected?— make sure you've selected a server in the Command Center
  • Server connected? — the server status must be green (Connected)
  • Rate limit — you may have hit your monthly AI request limit

Agent using too much CPU or memory

The agent normally uses <1% CPU and ~15 MB RAM. If usage is higher:

  • Check agent version: helmrelay-agent --version
  • Update to latest — re-run the install command from your dashboard (Server → Settings → Update Agent)
  • Restart the agent: sudo systemctl restart helmrelay-agent
  • If the issue persists, enable debug logging in /etc/helmrelay/agent.yaml and contact support

Can't connect through proxy

Add proxy settings to the systemd service:

sudo systemctl edit helmrelay-agent

Add:

[Service]
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1"

Then restart:

sudo systemctl daemon-reload
sudo systemctl restart helmrelay-agent

Regenerating the connection token

If your token is compromised or not working:

  1. Go to Dashboard → Servers → Your Server → Settings
  2. Click Regenerate Token
  3. Copy the new token
  4. Update /etc/helmrelay/agent.yaml on your server with the new token
  5. Restart the agent: sudo systemctl restart helmrelay-agent

Still stuck?

If none of the above helps, contact support with:

  • Your server OS and version (cat /etc/os-release)
  • Agent version (helmrelay-agent --version)
  • Last 50 lines of agent logs (journalctl -u helmrelay-agent -n 50)

See also