Skip to content

Agent (Linux / Windows)

The Vesana Agent is a single, statically linked Go program with no runtime dependencies. It runs as a systemd service (Linux) or Windows service.

Prerequisites

  • Outbound HTTPS to the Vesana server — port 443 or the port of the agent server address (e.g. 8443 with the agent gateway). The agent does not use an HTTP proxy (see Proxy).
  • Linux: amd64, arm64 or armv6/armv7 (e.g. Raspberry Pi, LoxBerry) with systemd (Debian, Ubuntu, RHEL, Rocky, AlmaLinux, SUSE, Arch); install as root
  • Windows: Server 2016+ or Windows 10+ (amd64)

Step 1 — Create host in Vesana

Unless already done: create the host. See Adding hosts.

Step 2 — Generate agent token

Open the host → Manage host → Connection tab → under "Monitoring sources" Set up agent (requires the "Manage agents" permission):

  1. The token is shown exactly once — copy it immediately.
  2. Below it are ready-made install commands for Windows and Linux with token and server address filled in. The easiest way is to copy the matching command from there.

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. Without token and address (bash <(wget -qO- https://your-domain.tld/agent/install.sh)) the installer asks for both interactively — the token then stays out of the shell history.

What happens:

  1. Download and verify the binary (real Linux binary, test run with --version) — if that fails, the installer aborts and a running agent is left untouched
  2. Binary into /usr/local/bin/vesana-agent
  3. Config in /etc/vesana-agent/config.yaml (chmod 600), state in /var/lib/vesana-agent
  4. systemd unit at /etc/systemd/system/vesana-agent.service
  5. Enable and start the service; if it does not start, the installer shows status and journal

Safe to re-run — overwrites binary and config.

# 1. Download binary
# amd64 · arm64 · arm for 32-bit ARM
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 and directories
sudo mkdir -p /etc/vesana-agent /var/lib/vesana-agent /var/log/vesana-agent
sudo chmod 700 /var/lib/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 Monitoring Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/vesana-agent --config /etc/vesana-agent/config.yaml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 4. Activate
sudo systemctl daemon-reload
sudo systemctl enable --now vesana-agent

Restart=always is required: after a self-update the agent exits cleanly and relies on systemd to restart it. With Restart=on-failure it would stay down after the first update.

  1. In the "Set up agent" dialog click vesana-agent-setup.exe. The download comes with the server address pre-filled (and, if needed, the certificate fingerprint, see below).
  2. Run it as administrator — the wizard opens.
  3. Inputs:
    • Server URL (pre-filled)
    • Agent token from step 2
    • Tick "Self-signed Zertifikat (TLS-Pruefung ueberspringen)" only if the server has a self-signed certificate without a fingerprint
  4. Install — the wizard puts the program into C:\Program Files\Vesana Agent\, the config into C:\ProgramData\Vesana\Agent\config.yaml (SYSTEM and Administrators only), registers the service and starts it.

The service is VesanaAgent and starts at boot.

Without a GUI (e.g. Server Core) the same installer runs silently: vesana-agent-setup.exe /S /TOKEN=vesana_agent_xxx /SERVER=https://your-domain.tld (optional /INSECURE=1). If token or server is missing it exits with code 2.

In an administrator PowerShell (the ready command with token is shown in the "Set up agent" dialog):

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
& ([scriptblock]::Create(
    (New-Object Net.WebClient).DownloadString('https://your-domain.tld/agent/install.ps1')
)) -Token 'vesana_agent_xxx' -Server 'https://your-domain.tld'

Also works on Server Core (PowerShell 5.1 and 7). Safe to re-run: an existing agent is only replaced after a successful download. More parameters: -Lock (turn on Agent Lock right away), -SkipTlsCheck (self-signed certificate without fingerprint), -Instance (second agent).

Command prompt as Administrator:

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

REM 2. Install
mkdir "C:\Program Files\Vesana Agent"
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

On the manual path the config keeps the permissions Windows assigns. The setup wizard and the PowerShell installer restrict it to SYSTEM and Administrators — use one of them if you can.

Self-signed certificate: certificate pin

If your Vesana server presents a certificate under the agent server address that a normal client does not trust (self-signed stack certificate, private CA, agent gateway port), the install commands from Vesana automatically carry a certificate pin — the SHA-256 fingerprint of exactly that certificate:

  • Linux: the download uses curl --pinnedpubkey, the command sets VESANA_CERT_PIN=… VESANA_CERT_SPKI_PIN=… (curl must be installed; wget has no pinning).
  • Windows: the PowerShell command already checks the installer download against the fingerprint and passes -CertPin; the setup wizard gets the pin built in on download.
  • The agent writes it as server_cert_sha256 into its config and from then on accepts the normal certificate chain or exactly this certificate — never "anything". TLS verification stays on.

If the server has a valid certificate (including your own reverse proxy with a valid certificate in front of the agent server address), the command carries no pin. If the Linux installer aborts with "Zertifikats-Pin gesetzt, aber kein Schlüssel-Pin", the command comes from an older version — copy it again from Vesana.

The checkbox "The server uses a self-signed certificate (skip TLS verification)" on the other hand turns verification off entirely (insecure_skip_verify: true). Only use it when no pin is offered.

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:

systemctl list-units 'vesana-agent*' --type=service
ls -d /etc/vesana-agent*

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?

Get-Service VesanaAgent*

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

On the host page the agent chip should flip to Online within a short time (under "Manage host → Connection" with the agent version next to it). 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.

Open PowerShell as Administrator and run:

& "C:\Program Files\Vesana Agent\vesana-agent.exe" test

Run as Administrator, because the service runs as LocalSystem — as a normal user some checks (services, event log) can behave differently than in service mode.

sudo vesana-agent test

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:

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

The Windows service does not write to the event log but to C:\ProgramData\Vesana\Agent\agent.log:

Get-Service VesanaAgent
Get-Content "$env:ProgramData\Vesana\Agent\agent.log" -Tail 50 -Wait

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/crit_pattern (regex); exit code other than 0 = CRITICAL
agent_script Script from the script library or local path on the host Script selection, script values
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: open the host → Manage host → Connection → at the agent Renew token.

  1. The old token is invalid immediately; the agent on the machine now gets 401.
  2. Copy the new token once.
  3. Enter it on the machine: vesana-agent reconfigure (asks for server URL and token, see Commands on the host) and restart the service — or run the install command again with the new token.

Revoke token (same place) removes access without issuing a new one: the agent stops, and the host is no longer an agent host.

Proxy

The agent always connects directly to the Vesana server. It does not evaluate proxy environment variables such as HTTPS_PROXY — not for updates either. If traffic out of the network has to go through a proxy, you need a firewall rule for outbound HTTPS to the agent server address, or a collector that checks the devices from a network with access.

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:

2026-07-04 10:15:03  INFO   Results sent  checks=5

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 replaced via "Renew token"
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

  1. Firewall: outbound 443 (or gateway port) to the server open?
  2. DNS: getent hosts your-domain.tld (Linux) / nslookup your-domain.tld (Windows)
  3. TLS certificate: self-signed? Use the install command from Vesana (it carries the certificate pin), add the certificate to the system certificate store, or as a last resort set insecure_skip_verify: true in the config
  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 — certificate invalid or self-signed without pin
401 Unauthorized Token wrong, revoked or renewed
410 Gone Host permanently deleted in Vesana — the agent stops (see Lifecycle)
connection refused Server not there or wrong port

Service won't start

# Linux: run the agent in the foreground (stop the service first)
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 /var/lib/vesana-agent /var/log/vesana-agent
sudo rm /usr/local/bin/vesana-agent
sudo systemctl daemon-reload

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.

It's easier from within Vesana: delete the host (or “Remove agent” on the agent chip) and choose “Uninstall” — the agent then removes itself. What happens to the agent when you deactivate, delete or restore: Deactivate, delete, restore.

Next