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:
- Set up agent
- Token shown exactly once
- Copy immediately
Step 3 — Install agent¶
On the target machine as root:
Replace TOKEN with the token from step 2 and your-domain.tld with your server.
What happens:
- Distro detection (Debian/RHEL/SUSE/Arch)
- Binary into
/usr/local/bin/vesana-agent - Config in
/etc/vesana-agent/config.yaml(chmod 600) - systemd unit at
/etc/systemd/system/vesana-agent.service 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
- Download from server downloads page:
vesana-agent-setup.exe - Double-click — wizard opens
- Inputs:
- Server URL:
https://your-domain.tld - Agent token from step 2
- Server URL:
- 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
Second agent on the same machine¶
A machine can report to two Vesana instances — e.g. your own instance plus a second one (test, service provider, app.vesana.org). For that, a second agent runs next to the first under its own name: own service, own config, own state. The first agent is left untouched. The agent token comes from the other instance (create the host there, "Set up agent", copy the token).
Not the default
One agent per machine is the norm. The second agent is for this special case — it is not set up through the UI but with the installer parameter below.
The installer takes an instance name (lowercase letters, digits, hyphen — max. 32 characters):
wget -qO- https://second-instance.tld/agent/install.sh | VESANA_INSTANCE=second bash -s -- TOKEN https://second-instance.tld
The name is appended to everything:
| first agent | second agent (second) |
|
|---|---|---|
| Service | vesana-agent |
vesana-agent-second |
| Binary | /usr/local/bin/vesana-agent |
/usr/local/bin/vesana-agent-second |
| Config | /etc/vesana-agent/config.yaml |
/etc/vesana-agent-second/config.yaml |
| State | /var/lib/vesana-agent |
/var/lib/vesana-agent-second |
| Logs | /var/log/vesana-agent |
/var/log/vesana-agent-second |
Operate as usual, just with the name:
systemctl status vesana-agent-second
journalctl -u vesana-agent-second -f
vesana-agent-second --config /etc/vesana-agent-second/config.yaml test
Removal: as under Uninstall, with -second appended to
service, binary and directories.
Which agents run on this machine? The instance name lives in the service and directory names — it is not stored anywhere else:
The PowerShell installer takes -Instance (letters, digits, hyphen —
max. 32 characters). The NSIS wizard does not know about a second agent —
always use the PowerShell variant for it:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
& ([scriptblock]::Create(
(New-Object Net.WebClient).DownloadString('https://second-instance.tld/agent/install.ps1')
)) -Token 'vesana_agent_xxx' -Server 'https://second-instance.tld' -Instance 'Second'
| first agent | second agent (Second) |
|
|---|---|---|
| Service | VesanaAgent |
VesanaAgent-Second |
| Program | C:\Program Files\Vesana Agent |
C:\Program Files\Vesana Agent-Second |
| Config + log | C:\ProgramData\Vesana\Agent |
C:\ProgramData\Vesana\Agent-Second |
Removal (administrator PowerShell):
& "$env:ProgramFiles\Vesana Agent-Second\vesana-agent.exe" --service-name VesanaAgent-Second uninstall
Remove-Item -Recurse -Force "$env:ProgramFiles\Vesana Agent-Second"
Remove-Item -Recurse -Force "$env:ProgramData\Vesana\Agent-Second"
Which agents run on this machine?
Both agents update themselves independently from their respective server. Checks run twice (each instance measures on its own) — that is intended and costs next to nothing on the machine.
Step 4 — Verify¶
In the UI: agent status on the host detail should flip to online within a short time (green dot). The agent sends a heartbeat roughly every 20 seconds — that's what drives the online status. The actual check configuration (new/changed checks, version) is fetched separately, roughly every 5 minutes.
Test checks immediately — vesana-agent test¶
Right after install, it's worth running a test pass instead of waiting for the first regular check cycle. The command vesana-agent test runs every check configured by the server once, prints each result live in the console (status, first line of the message, duration) and then sends the batch to the server. It's the quick way to confirm the configuration arrived and the checks return plausible values.
The config (server URL + token) is found automatically — Windows C:\ProgramData\Vesana\Agent\config.yaml, Linux /etc/vesana-agent/config.yaml. If it lives elsewhere: vesana-agent test --config <path>.
Typical output: Server: …, Connected as host "…" — N checks configured, then the results line by line and a summary (Result: 2 OK, 1 WARNING …). Plain-text diagnostics on problems: 401/403 = check the token, 404 = check the server URL, "0 checks" = add agent checks in the portal first. The running service keeps sending in parallel — duplicate data points are harmless in the push model.
\"unknown command: test\"?
Then the installed agent is too old for the command. Agents update
automatically (~5 min) — after that test is available.
Logs:
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.
Threshold changes (warn/critical) take effect immediately, independent of that: the server applies changed thresholds server-side to every incoming result, regardless of when the agent last fetched its config. Other config changes (e.g. event log filters, service exclusions) do need the agent's next config poll — normally the full 5 minutes, but the server can pull that poll forward so the change takes effect within roughly 60 seconds.
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) |
agent_containers |
Containers (Docker) — unhealthy, crash loops, exited required containers (Linux only, reads the Docker socket) | required/exception lists with wildcards, thresholds on the number of problems |
The event log check also runs on Linux (journald). On Windows the CPU measurement reads the performance counters directly — locale-neutral and working on Windows Server 2025 without wmic. PowerShell scripts are stored with a UTF-8 byte-order mark so umlauts and special characters in a script do not cause syntax errors. Hardware telemetry (SMART, temperatures, interface throughput) and the Docker tab need a current agent — the update arrives automatically. Agents of the old 2.x line that got stuck permanently need a one-time reinstall.
Token rotation¶
If a token is compromised:
- Host detail → Agent → Revoke token
- Old agent stops authenticating (401)
- Generate new token
- Update
/etc/vesana-agent/config.yaml(orC:\ProgramData\Vesana\Agent\config.yaml) - 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
Troubleshooting¶
agent.log — first stop¶
If the agent is running but no data arrives, agent.log is the fastest way to find out why. It's plain text (no structured log format), local time, level spelled out:
File location:
| Platform | Path |
|---|---|
| Linux | next to the config, so /etc/vesana-agent/agent.log |
| Windows | C:\ProgramData\Vesana\Agent\agent.log |
The agent logs typical causes as a clear error instead of swallowing them silently:
| Log content | Meaning |
|---|---|
401/403 |
Check the token — wrong, revoked, or assigned to a different host |
404 |
Check the server URL — path/domain is wrong |
| „0 checks" | Host has no services assigned yet — see step 5 above |
Non-OK results are additionally logged with a plain-text message (OK results stay at debug level so the log doesn't flood).
Agent not reporting¶
- Firewall: outbound 443 to server open?
- DNS:
getent hosts your-domain.tld(Linux) /nslookup your-domain.tld(Windows) - TLS cert: self-signed? Set
--insecurein config or import cert into system trust store - Token: exact, no whitespace/newlines
- 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¶
NSIS uninstaller via Settings → Apps → Installed apps → "Vesana Agent". Or (PowerShell as Administrator):
& "$env:ProgramFiles\Vesana Agent\uninstall.exe" /S
Remove-Item -Recurse -Force "$env:ProgramData\Vesana\Agent" -ErrorAction SilentlyContinue
Full guide including forced service removal: Uninstall → Remove the agent.
After uninstall: revoke token in Vesana, otherwise the host counts as „has agent" forever.
Next¶
- Agent versioning — understand auto-update
- Monitoring → Check types — all agent checks
- Monitoring → Scripts — custom scripts via
agent_script