Install the agent

The agent is part of Vaicoa Pro and Vaicoa Team, for cloud and dedicated (Robot) servers.

The Vaicoa agent runs on your Linux servers and sends what the Hetzner Cloud API cannot see. With it, you get:

• Disk, RAM and load charts on the server’s detail screen, with alerts for a filling disk and for memory pressure.
• Warning log lines of the last 72 hours in log context, with alerts for critical lines and bursts of errors.
• Job reports from your backups and cron jobs.
• Dedicated servers. They are not in the Hetzner Cloud API, so the agent is the only way to see them.
• An alert when the server stops reporting: stopped reporting after 5 minutes without metrics, critical for a dedicated server and a warning for a cloud server that Hetzner still reports as running. See Alert rules.

What you need: a Linux server with systemd, curl and apt (Debian, Ubuntu) or dnf/yum (RHEL family), x86-64 or Arm64, and root access. All details: Agent reference.

Install on one server

1. In the portal, open Monitored Servers and click Add server. On One server, enter a Server name, pick the Kind (Cloud or Dedicated) and, for a cloud server, its Hetzner project. Click Register server.

2. Copy the agent token. It is shown once and stored hashed, like a password.

3. On the server, run the command the portal shows, as root:

   curl -fsSL https://get.vaicoa.com/agent | sh -s -- --token <agent_token>

   It sets up two signed package repositories (Vaicoa’s and Vector’s), installs the cloudviewer-agent package with apt or dnf and registers the server.

4. Within a minute, the server shows Connected in Monitored Servers.

Caution

For a Hetzner Cloud server, use a fleet enrollment token, even for a single server. Only fleet enrollment links the agent to the server in your project. With a per-server token, Vaicoa cannot link them yet: the server’s detail screen shows no agent charts, jobs or log lines, and deleting the server does not retire it. Per-server tokens are for dedicated servers.

After that, nothing on the server is managed by a script: the agent is an OS package, updated with your normal apt upgrade or dnf upgrade. Each server takes one of your plan’s monitored-server slots.

Install with your package manager

If you would rather not pipe a script into a shell, add the repository yourself, and Vector’s repository if the server does not have it yet.

Debian, Ubuntu

curl -fsSL https://get.vaicoa.com/keys/cloudviewer.gpg \
  -o /usr/share/keyrings/cloudviewer.gpg
echo "deb [signed-by=/usr/share/keyrings/cloudviewer.gpg] https://get.vaicoa.com/apt stable main" \
  > /etc/apt/sources.list.d/cloudviewer.list
apt update && apt install cloudviewer-agent
cloudviewer-agent enroll --token <agent_token>

RHEL family

Create /etc/yum.repos.d/cloudviewer.repo:

[cloudviewer]
name=Vaicoa
baseurl=https://get.vaicoa.com/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://get.vaicoa.com/keys/cloudviewer.gpg

dnf install cloudviewer-agent
cloudviewer-agent enroll --token <agent_token>

The package does nothing until enroll has run, and running it again is always safe. For cloud-init, Ansible and similar tools, write CV_AGENT_TOKEN=<agent_token> to /etc/cloudviewer-agent/agent.env (mode 0600) before installing; the package then registers the server during installation.

Enroll a fleet

For Hetzner Cloud servers, one or many, and for servers an autoscaler creates, one fleet enrollment token replaces the per-server tokens.

1. In Monitored Servers → Add server → Fleet enrollment, give the token a Label, pick the Hetzner project and click Mint enrollment token. Copy it; it is shown once.

2. Run this on each server as root, or from cloud-init, Terraform user_data or Ansible:

   curl -fsSL https://get.vaicoa.com/agent | sh -s -- --enroll-token <fleet_token>

Each server identifies itself through Hetzner’s metadata service. Vaicoa checks it against the project’s inventory and registers it as its own monitored server, with its own token. The fleet token can only register servers and is not stored on them, so it is safe in Ansible Vault or a CI secret store. Running the command again changes nothing. Dedicated servers have no metadata service and need per-server tokens.

Containers and Kubernetes

Systems without apt, dnf or systemd, such as Alpine, can run the container image. On Kubernetes, the Helm chart runs a DaemonSet. With a fleet token, each node registers as its own server, and replacement nodes register themselves. The nodes must be Hetzner Cloud servers.

kubectl create secret generic cloudviewer-agent \
  --from-literal=enroll-token=<fleet_token>
helm install cloudviewer-agent \
  oci://ghcr.io/cloudviewer-app/charts/cloudviewer-agent \
  --set existingSecret=cloudviewer-agent

Values and the single-node case are in the chart README.

Rotate a token without a gap

A server can have two active tokens at once:

1. In Monitored Servers, click Rotate agent token. The new token is shown once; both work.
2. Update your hosts (cloudviewer-agent enroll --token <new_token>) and secret stores. The row shows when each token was last used, so you can see when everything has switched. This can take days.
3. Click Complete rotation. The old token stops working everywhere within about ten seconds.

Revoke agent token invalidates every token of a server at once. Issue new token reactivates a revoked server and keeps its history.

Remove a server

• A fleet-enrolled cloud server you delete through the Hetzner API, for example with terraform destroy or an autoscaler, is retired on its own: no offline alert, tokens revoked, plan slot freed at once.
• On the server, apt purge cloudviewer-agent or dnf remove cloudviewer-agent removes the configuration, token and buffered data, and the server unregisters itself.
• In the portal, Remove server invalidates the token. The server is not touched, so remove the package too.

A retired server stays visible for 72 hours with a Retired badge, so its logs and job history can still be read. Then the server and its data are deleted. What stays installed, apt remove and Kubernetes: reference.

A server that is retired or removed this way raises no alert. A server that still exists but stops sending raises stopped reporting after 5 minutes.

What the agent does and does not do

The agent sends metrics every 30 seconds and log lines at WARN level or higher, nothing else, and masks obvious secrets on your server before a line is sent. It opens no inbound ports, runs as unprivileged system users and cannot change anything on your servers or in your Hetzner projects. Settings from the portal reach it as a few declared parameters, never as code. If a server sends too much, only that server is rate-limited.

Agent referenceSystems, packages, files, commands, flags, what it collects and where it connects.

Get told when a job failsReport backups and cron jobs with the server's agent token.