Agent Overview

How the HelmRelay agent works on your server.

What is the agent?

The HelmRelay agent is a lightweight binary that runs on your Linux VPS as a systemd service. It maintains a secure WebSocket connection to HelmRelay cloud and:

Reports system metrics (CPU, RAM, disk, network) every 10 seconds
Executes commands sent from the dashboard
Sends command output back in real-time
Auto-updates when new versions are available

Architecture

┌─────────────────┐         ┌──────────────────────┐
│   Your Server   │  WSS    │   HelmRelay Cloud    │
│                 │ ◄─────► │                      │
│  helmrelay-agent│  :443   │  Dashboard + AI      │
│  (systemd)      │         │  Metrics storage     │
└─────────────────┘         └──────────────────────┘

All communication is initiated outbound from the agent. No inbound ports need to be opened on your server.

File locations

Path	Description
`/usr/local/bin/helmrelay-agent`	Agent binary
`/etc/helmrelay/agent.yaml`	Configuration file (token, server URL)
`/etc/systemd/system/helmrelay-agent.service`	Systemd service unit
`/var/lib/helmrelay/`	Data directory
`/var/log/helmrelay/`	Log directory

Configuration

The agent config file at /etc/helmrelay/agent.yaml:

server_url: https://api.helmrelay.com
token: hr_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
server_id: your-server-id
log_level: info    # debug, info, warn, error

After changing the config, restart the agent:

sudo systemctl restart helmrelay-agent

Useful commands

# Check status
sudo systemctl status helmrelay-agent

# View logs (last 100 lines)
sudo journalctl -u helmrelay-agent -n 100 --no-pager

# Follow logs in real-time
sudo journalctl -u helmrelay-agent -f

# Restart agent
sudo systemctl restart helmrelay-agent

# Check version
helmrelay-agent --version

Auto-updates

The agent checks for updates periodically and applies them automatically with zero downtime. The update process:

Agent checks for new version
Downloads the new binary
Verifies the checksum
Replaces the binary and restarts

You can also trigger a manual update from the dashboard or re-run the install command with your token:

Install command

$ curl -sSL https://cdn.helmrelay.com/install.sh | sudo bash -s -- --token YOUR_TOKEN --server-id YOUR_SERVER_ID

Resource usage

Resource	Usage
RAM	~15 MB
CPU	<1% average
Network	~50 KB/min outbound
Disk	~50 MB total