Skip to content

Agent (Linux / Windows)

The Vesana Agent is a single Go binary — statically linked (CGO_ENABLED=0), ~6.5 MB, no runtime dependencies. Runs as systemd service (Linux) or Windows service.

Prerequisites

  • Outbound HTTPS 443 to the Vesana server
  • Linux: systemd (Debian, Ubuntu, RHEL, AlmaLinux, SUSE, Arch all OK); install as root
  • Windows: Server 2016+ or Windows 10+ (amd64)

Step 1 — Create host in Vesana

Unless already done: create a host with agent_capable profile. See Adding hosts.

Step 2 — Generate agent token

On the host detail page:

  1. Set up agent
  2. Token shown exactly once
  3. Copy immediately

Step 3 — Install agent

On the target machine as root:

wget -qO- https://your-domain.tld/agent/install.sh | bash -s -- TOKEN https://your-domain.tld

Replace TOKEN with the token from step 2 and your-domain.tld with your server.

What happens:

  1. Distro detection (Debian/RHEL/SUSE/Arch)
  2. Binary into /usr/local/bin/vesana-agent
  3. Config in /etc/vesana-agent/config.yaml (chmod 600)
  4. systemd unit at /etc/systemd/system/vesana-agent.service
  5. systemctl enable --now vesana-agent

Re-run safe — overwrites binary + config.

# 1. Download binary
wget https://your-domain.tld/agent/vesana-agent-linux-amd64 -O /tmp/vesana-agent
chmod +x /tmp/vesana-agent
sudo mv /tmp/vesana-agent /usr/local/bin/vesana-agent

# 2. Create config
sudo mkdir -p /etc/vesana-agent
sudo tee /etc/vesana-agent/config.yaml > /dev/null <<'EOF'
server: "https://your-domain.tld"
token: "vesana_agent_YOUR_TOKEN_HERE"
log_level: "info"
EOF
sudo chmod 600 /etc/vesana-agent/config.yaml

# 3. systemd unit
sudo tee /etc/systemd/system/vesana-agent.service > /dev/null <<'EOF'
[Unit]
Description=Vesana Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/vesana-agent --config /etc/vesana-agent/config.yaml
Restart=on-failure
RestartSec=5
User=root

[Install]
WantedBy=multi-user.target
EOF

# 4. Activate
sudo systemctl daemon-reload
sudo systemctl enable --now vesana-agent
  1. Download from server downloads page: vesana-agent-setup.exe
  2. Double-click — wizard opens
  3. Inputs:
    • Server URL: https://your-domain.tld
    • Agent token from step 2
  4. Install — wizard installs binary into C:\Program Files\Vesana\Agent\, writes config, registers Windows service

Service is VesanaAgent and starts at boot.

Command prompt as Administrator:

REM 1. Download
cd %TEMP%
curl -O https://your-domain.tld/agent/vesana-agent-windows-amd64.exe

REM 2. Install
move vesana-agent-windows-amd64.exe "C:\Program Files\Vesana\Agent\vesana-agent.exe"

REM 3. Config (PowerShell)
powershell -Command "New-Item -ItemType Directory -Force 'C:\ProgramData\Vesana\Agent'"
powershell -Command "@'
server: ""https://your-domain.tld""
token: ""vesana_agent_YOUR_TOKEN_HERE""
log_level: ""info""
'@ | Set-Content -Path 'C:\ProgramData\Vesana\Agent\config.yaml'"

REM 4. Install service and start
"C:\Program Files\Vesana\Agent\vesana-agent.exe" install
net start VesanaAgent

Step 4 — Verify

In the UI: agent status on the host detail should flip to online within 30 s (green dot).

Logs:

sudo systemctl status vesana-agent
sudo journalctl -u vesana-agent -f

Event Viewer → Windows Logs → Application → Source „VesanaAgent"

Or PowerShell:

Get-EventLog -LogName Application -Source VesanaAgent -Newest 20

Step 5 — Assign checks

If the profile has auto_add checks, they're already there. Otherwise add services manually on the host detail.

The agent fetches config every 5 minutes — new checks appear with a small delay.

Available agent check types

Check type What it checks Config
agent_cpu CPU usage % (over time) –
agent_memory RAM usage % –
agent_disk Disk usage per mount path (e.g. /, C:)
agent_service OS service / systemd unit status service (name)
agent_process Process running? process (name or pattern)
agent_eventlog Windows event log log, level, minutes
agent_custom Run own command command, ok_pattern/warn_pattern/crit_pattern
agent_script Server-managed script script_id
agent_services_auto All auto-start services (Windows) exclude (list)

Token rotation

If a token is compromised:

  1. Host detail → Agent → Revoke token
  2. Old agent stops authenticating (401)
  3. Generate new token
  4. Update /etc/vesana-agent/config.yaml (or C:\ProgramData\Vesana\Agent\config.yaml)
  5. Restart service

Or: re-install via one-command installer with new token.

Proxy / DNS

If the agent needs an HTTPS proxy:

sudo mkdir -p /etc/systemd/system/vesana-agent.service.d
sudo tee /etc/systemd/system/vesana-agent.service.d/proxy.conf > /dev/null <<'EOF'
[Service]
Environment="HTTPS_PROXY=http://proxy.local:8080"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF
sudo systemctl daemon-reload
sudo systemctl restart vesana-agent

Service env via registry:

powershell -Command "Set-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Services\VesanaAgent' -Name Environment -Value @('HTTPS_PROXY=http://proxy.local:8080','NO_PROXY=localhost,127.0.0.1')"
Restart-Service VesanaAgent

Troubleshooting

Agent not reporting

  1. Firewall: outbound 443 to server open?
  2. DNS: getent hosts your-domain.tld (Linux) / nslookup your-domain.tld (Windows)
  3. TLS cert: self-signed? Set --insecure in config or import cert into system trust store
  4. Token: exact, no whitespace/newlines
  5. Logs

Common errors:

Log line Cause
dial tcp: lookup vesana.example: no such host DNS
x509: certificate signed by unknown authority TLS — invalid or self-signed cert
401 Unauthorized Wrong token
403 Forbidden Token belongs to another host (re-issued in DB?)
connection refused Server not there or wrong port

Service won't start

# Linux: foreground run shows direct output
sudo /usr/local/bin/vesana-agent --config /etc/vesana-agent/config.yaml

# Windows
"C:\Program Files\Vesana\Agent\vesana-agent.exe" --config "C:\ProgramData\Vesana\Agent\config.yaml"

Foreground output reveals problems hidden as service.

Auto-update stuck

See Agent versioning.

Uninstall

sudo systemctl stop vesana-agent
sudo systemctl disable vesana-agent
sudo rm /etc/systemd/system/vesana-agent.service
sudo rm -rf /etc/vesana-agent
sudo rm /usr/local/bin/vesana-agent
sudo systemctl daemon-reload

NSIS uninstaller via Programs & Features. Or:

"C:\Program Files\Vesana\Agent\vesana-agent.exe" uninstall
rmdir /s /q "C:\Program Files\Vesana\Agent"
rmdir /s /q "C:\ProgramData\Vesana\Agent"

After uninstall: revoke token in Vesana, otherwise the host counts as „has agent" forever.

Next