Agent

Der Agent ist Teil von Vaicoa Pro und Vaicoa Team. Wie du ihn installierst: Agent installieren.

Der Vaicoa-Agent ist ein OS-Paket, cloudviewer-agent, rund um den Upstream-Collector Vector. Er sendet Metriken und Warn-Log-Zeilen von einem Linux-Server an Vaicoa, und Job-Reports über cloudviewer-report. Der Gerätemodus nutzt ihn nicht.

Unterstützte Systeme

Familie	Paketmanager	Paket
Debian, Ubuntu	apt	.deb
RHEL-Familie: Rocky Linux, AlmaLinux, CentOS Stream, Fedora	dnf oder yum	.rpm

Voraussetzung
Architektur	x86-64 und Arm64 (etwa Hetzners CAX-Server). Das Paket enthält keinen kompilierten Code (all / noarch); Vectors Repositories liefern den Collector für jede Architektur
Init-System	systemd
Werkzeuge	curl. Auf Debian und Ubuntu außerdem gpg, wenn der Installer Vectors Repository hinzufügen muss
Installation	als root
Getestet	die komplette Installation, vom Paket bis zu den ersten Daten, wurde auf Ubuntu 24.04, Debian 12 und Rocky Linux 9 getestet
Andere Systeme	Alpine, NixOS und Systeme ohne systemd: das Container-Image oder die Dateien aus dem Verzeichnis agent/ des Repositorys, von Hand installiert

Pakete und Repositories

Paket	cloudviewer-agent: wenige KB lesbarer Shell-Skripte und systemd-Units, keine eigenen Binaries. Gebaut aus dem Open-Source-Repository cloudviewer-app/cloudviewer-agent (Apache-2.0)
Version	<year>.<quarter>.<patch>, zum Beispiel 2026.3.0
Collector	das Paket vector (0.57.0 oder neuer) aus Vectors eigenem signierten Repository; cloudviewer-agent hängt davon ab
Signaturschlüssel	https://get.vaicoa.com/keys/cloudviewer.gpg
apt	deb [signed-by=/usr/share/keyrings/cloudviewer.gpg] https://get.vaicoa.com/apt stable main in /etc/apt/sources.list.d/cloudviewer.list
dnf, yum	/etc/yum.repos.d/cloudviewer.repo mit baseurl=https://get.vaicoa.com/rpm, gpgcheck=1, repo_gpgcheck=1
Vector, apt	https://apt.vector.dev/ stable vector-0 in /etc/apt/sources.list.d/vector.list, Schlüssel von keys.datadoghq.com in /usr/share/keyrings/datadog-archive-keyring.gpg
Vector, dnf	https://yum.vector.dev/stable/vector-0/$basearch/ in /etc/yum.repos.d/vector.repo
Updates	mit dem Paketmanager: apt upgrade, dnf upgrade
Vector festpinnen	Vectors Repositories behalten jede Version, apt-Preferences oder dnf versionlock funktionieren also

Der Installer fügt Vectors Repository nur hinzu, wenn vector nicht installiert ist und weder vector.list noch vector.repo existiert.

Installationsbefehle

# Ein Server, mit seinem Token aus Überwachte Server → Server hinzufügen → Ein Server
curl -fsSL https://get.vaicoa.com/agent | sh -s -- --token <agent_token>

# Hetzner-Cloud-Server, mit einem Flotten-Token (Server hinzufügen → Flotten-Registrierung)
curl -fsSL https://get.vaicoa.com/agent | sh -s -- --enroll-token <fleet_token>

# Den Agent entfernen
curl -fsSL https://get.vaicoa.com/agent | sh -s -- --uninstall

Der Installer prüft auf root, systemd und curl, erkennt apt, dnf oder yum, fügt die Repositories hinzu, installiert cloudviewer-agent mit dem Paketmanager und führt cloudviewer-agent enroll aus. Danach verwaltet kein Skript mehr etwas auf dem Server.

Flag	Bedeutung
--token <t>	Agent-Token pro Server aus dem Portal, einmal angezeigt. Optional, wenn /etc/cloudviewer-agent/agent.env schon existiert
--enroll-token <t>	Registrierungs-Token für die Flotte. Nur Hetzner-Cloud-Server: Der Server identifiziert sich über den Metadaten-Dienst. Nicht mit --token kombinierbar
--facade-url <u>	Basis-URL der Vaicoa API. Standard https://api.vaicoa.com
--uninstall	Entfernt den Agent, seine Konfiguration, sein Token und gepufferte Daten, über den Paketmanager
--help	Zeigt die Verwendung

Vorab eingerichtete Installation (cloud-init, Ansible, Terraform user_data): Schreib CV_AGENT_TOKEN=<agent_token> (oder CV_AGENT_ENROLL_TOKEN=<fleet_token>) nach /etc/cloudviewer-agent/agent.env, Modus 0600, bevor du das Paket installierst. Das Paket registriert den Server dann bei der Installation. cloudviewer-agent enroll ohne Flags macht dasselbe auf einem Server, der das Paket schon hat.

Token pro Server oder Flotten-Token

	Token pro Server	Registrierungs-Token für die Flotte
Erstellt unter	Überwachte Server → Server hinzufügen → Ein Server, eins pro Server	Server hinzufügen → Flotten-Registrierung, eins pro Rollout, für ein Projekt
Server	Beliebige	Nur Hetzner-Cloud-Server: identifiziert über den Metadaten-Dienst
Auf dem Server	In agent.env	Nicht gespeichert. Der Server erhält sein eigenes Token pro Server
Mit dem Cloud-Server in deinem Projekt verknüpft	Nein, noch nicht	Ja
Agent-Charts, Jobs und Log-Zeilen in der Detailansicht eines Cloud-Servers	Nein	Ja
Außer Dienst gestellt, wenn der Cloud-Server über die Hetzner API gelöscht wird	Nein	Ja
Dedizierte Server	Ja, mit eigener Detailansicht	Nicht möglich
Zuletzt benutzt	Während einer Rotation pro Token angezeigt	Liste Registrierungs-Tokens, pro Token
Entziehen	Agent-Token entziehen: Jedes Token des Servers funktioniert innerhalb von etwa zehn Sekunden nicht mehr	Registrierungs-Token entziehen: keine neuen Registrierungen; registrierte Server melden weiter

Die Flotten-Registrierung wird mit einer Meldung abgewiesen: bei einem unbekannten oder entzogenen Token, wenn die Server-Grenze des Plans erreicht ist, und für einen Server, der nicht im Projekt des Tokens ist.

Befehle

Befehl	Was er tut
cloudviewer-agent enroll --token <t>	Prüft das Token bei Vaicoa, schreibt agent.env und die Konfiguration, aktiviert und startet die Dienste. Erneut mit einem neuen Token ausgeführt, ersetzt es das Token direkt
cloudviewer-agent enroll --enroll-token <t>	Flotten-Registrierung über den Metadaten-Dienst der Hetzner Cloud, dann dasselbe wie oben mit dem neuen eigenen Token des Servers. Tut nichts auf einem Server, der schon registriert ist
cloudviewer-agent enroll	Registriert aus einer vorhandenen agent.env
cloudviewer-agent status	Registriert oder nicht, der Zustand der Dienste, die Konfigurationsversion und die Vector-Version. Endet mit 3, wenn nicht registriert
cloudviewer-agent render	Baut vector.yaml aus den letzten Parametern neu, ohne Netzwerk. Das Paket führt es bei Upgrades aus
cloudviewer-agent uninstall	Meldet den Server ab, stoppt die Dienste und entfernt Konfiguration, Token und Daten. Das Paket bleibt installiert
cloudviewer-report	Wrapper für Job-Reports, siehe Job-Reports-API
systemctl status cloudviewer-agent	Der Collector-Dienst

enroll akzeptiert --facade-url <u> und --quiet. enroll, render und uninstall brauchen root. enroll erneut auszuführen ist immer sicher.

Dateien, Dienste und Nutzer

Pfad	Was
/usr/bin/cloudviewer-agent	Die Befehle oben
/usr/bin/cloudviewer-report	Wrapper für Job-Reports
/usr/libexec/cloudviewer-agent/fetch-config	Fragt Vaicoa jede Minute nach den Parametern
/usr/libexec/cloudviewer-agent/render-config	Baut vector.yaml aus den Parametern
/usr/libexec/cloudviewer-agent/fleet-enroll	Flotten-Registrierung
/usr/lib/systemd/system/cloudviewer-agent.service	Vector, mit der erzeugten Konfiguration
/usr/lib/systemd/system/cloudviewer-agent-config.service und .timer	Die Parameterprüfung, jede Minute
/usr/share/doc/cloudviewer-agent/README.md	Die README des Repositorys
/etc/cloudviewer-agent/agent.env	CV_AGENT_TOKEN und CV_AGENT_FACADE_URL. Modus 0600, Eigentümer cloudviewer-agent
/etc/cloudviewer-agent/manifest	Die zuletzt empfangenen Parameter
/etc/cloudviewer-agent/vector.yaml	Die erzeugte Konfiguration. Modus 0640, cloudviewer-agent:vector. Wird bei jeder Änderung neu geschrieben; nicht bearbeiten
/etc/cloudviewer-agent/config.etag	Version der letzten Parameter
/var/lib/cloudviewer-agent/	Vectors Puffer und Checkpoints, Eigentümer vector. Nicht /var/lib/vector, damit ein eigenes Vector daneben laufen kann

dpkg -L cloudviewer-agent oder rpm -ql cloudviewer-agent listet jede Datei, die das Paket installiert.

Nutzer	Führt aus	Darf
vector	cloudviewer-agent.service (der Collector)	journald und das Auth-Log über seine Gruppen systemd-journal und adm lesen; seine Konfiguration lesen, nicht schreiben. Angelegt vom Paket vector
cloudviewer-agent	cloudviewer-agent-config.service (die Parameterprüfung)	/etc/cloudviewer-agent schreiben. Angelegt vom Paket

Nach der Registrierung läuft nichts als root. Nur die Befehle, die du selbst ausführst (enroll, render, uninstall), tun das.

Was er erfasst

Daten	Quelle	Plan
CPU, Speicher, Load, Festplatten-I/O, Netzwerk und Dateisystembelegung pro Mountpoint, alle 30 Sekunden	Vectors Host-Metriken	Pro und Team
System-Log-Zeilen mit Priorität 0 bis 4 (emergency bis warning), aus allen Units	journald	Pro und Team
SSH- und sudo-Log-Zeilen	/var/log/auth.log oder /var/log/secure, falls das System eine davon schreibt	Team, nachdem ein Admin im Portal unter Log-Erfassung die Option SSH- und sudo-Log-Zeilen erfassen eingeschaltet hat
Job-Reports	cloudviewer-report oder dein eigener HTTP-Aufruf	Pro und Team

• Die App zeigt Charts für Speicher, Festplatte und Load aus dem Agent. CPU- und Netzwerk-Charts kommen aus der Hetzner Cloud API, nur Cloud-Server haben sie also.
• Zeilen deiner eigenen Dienste sind dabei, wenn sie mit Priorität Warning oder höher nach journald gehen, zum Beispiel logger -p user.warning -t backup "s3 sync retried 3 times, succeeded" oder systemd-cat -t myapp -p warning. Zeilen der Stufe Info werden nicht gesendet.
• Bevor eine Zeile den Server verlässt, werden die Werte nach authorization, bearer, password, passwd, secret, token und key sowie PEM-Blöcke mit privaten Schlüsseln durch [REDACTED] ersetzt. Vaicoa wendet dieselben Regeln noch einmal an, wenn die Zeile ankommt. Siehe Log-Kontext.
• Log-Zeilen werden 72 Stunden aufbewahrt, höchstens 2.000 Zeilen pro Server.
• Schaltest du SSH- und sudo-Zeilen aus, stoppen sie bei der nächsten Parameterprüfung jedes Servers, meist innerhalb einer Minute. Zeilen, die danach ankommen, werden abgewiesen.
• Sonst nichts: keine Anwendungs-Logs außer journald, keine Dateiinhalte, keine Prozessliste.
• Enthält der Plan des Teams den Agent nicht mehr, speichert Vaicoa nicht mehr, was er sendet. Auf dem Server ändert sich nichts.

Grenzen pro Server

Grenze	Wert	Darüber
Log-Zeilen	120 pro Minute	Verworfen. Die App sagt, dass Zeilen gedrosselt wurden
Länge einer Log-Zeile	2.048 Byte	Abgeschnitten
Metrik-Samples	10.000 pro Minute	Verworfen. Die App sagt, dass Metriken gedrosselt wurden
Neue Metrik-Serien	2.000 pro Stunde	Neue Serien verworfen; bekannte Serien werden weiter angenommen
Gespeicherte Log-Zeilen	72 Stunden, höchstens 2.000 Zeilen	Die ältesten zuerst entfernt
Job-Reports	siehe Job-Reports-API

Jede Grenze gilt für einen Server. Andere Server des Teams sind nicht betroffen.

Verbindungen nach außen

Der Agent baut nur Verbindungen nach außen auf. Er öffnet keinen eingehenden Port.

Ziel	Port	Wann
api.vaicoa.com	443	Immer: Parameter jede Minute, Metriken, Log-Zeilen, Job-Reports, Registrierung und Abmeldung
get.vaicoa.com	443	Installation und Update: Installer, Paket-Repository, Signaturschlüssel
apt.vector.dev oder yum.vector.dev	443	Installation und Update: das Paket vector
keys.datadoghq.com	443	Installation und Update: Vectors Signaturschlüssel
169.254.169.254	80	Nur Flotten-Registrierung: der Metadaten-Dienst der Hetzner Cloud, für die ID des Servers
ghcr.io	443	Nur Container und Kubernetes: Image und Helm-Chart

Der Installer hat keine Proxy-Option. Ein für die Dienste gesetztes HTTPS_PROXY ist ungetestet.

Wie Konfiguration deine Server erreicht

Planwechsel und Einstellungen aus dem Portal erreichen deine Server innerhalb einer Minute, ohne SSH-Zugang. Jede Minute fragt der Agent Vaicoa nach einer kleinen Menge deklarierter Parameter, etwa dem Plan und ob er journald-Zeilen sowie SSH- und sudo-Zeilen senden soll. Er prüft sie gegen eine feste Liste von Schlüsseln und Werten und baut seine Konfiguration lokal aus der Vorlage im Paket. Alles andere, etwa ein unbekannter Schlüssel, eine unbekannte Version oder eine vollständige Konfiguration, wird abgewiesen, und die letzte funktionierende Konfiguration bleibt.

Auf diesem Weg wird kein ausführbarer Code übertragen, und das Token reist nie in den Parametern mit. Selbst wenn die Server von Vaicoa kompromittiert wären, könnte ein Angreifer nur diese dokumentierten Einstellungen ändern, aber keinen Code auf deinen Servern ausführen.

Zustände

Im Portal (Überwachte Server):

Kennzeichnung	Bedeutung
Wartet	Registriert, noch keine Meldung
Verbunden	Letzte Meldung vor weniger als 5 Minuten
Veraltet	Letzte Meldung vor 5 Minuten bis 1 Stunde
Offline	Letzte Meldung vor mehr als 1 Stunde
Entzogen	Der Server hat kein aktives Token
Außer Dienst	Ein per Flotte registrierter Cloud-Server, der aus seinem Hetzner-Projekt gelöscht wurde, oder der Agent hat sich abgemeldet. 72 Stunden sichtbar, dann mit seinen Daten gelöscht

Ein per Flotte registrierter Server zeigt „selbst registriert über“ und das Label des Tokens. Während einer Rotation zeigt die Zeile, wann das alte und das neue Token zuletzt benutzt wurden.

In der App, für dedizierte Server:

Zustand	Bedeutung
Warten auf Agent	Noch keine Meldung
Agent verbunden	Der Agent hat in den letzten 5 Minuten gemeldet
Zuletzt gesehen …	Der Agent hat seit mehr als 5 Minuten nicht gemeldet; die Zeit ist die seiner letzten Meldung
Agent widerrufen	Der Server hat kein aktives Token
Ausgemustert	Wie Außer Dienst im Portal

Nach 5 Minuten ohne Metriken löst der Server stopped reporting aus (Alarmregeln).

Entfernen

Aktion	Meldet den Server ab	Entfernt vom Server
apt purge cloudviewer-agent	ja	Paket, Konfiguration, Token, gepufferte Daten
apt remove cloudviewer-agent	nein	nur die Paketdateien
dnf remove cloudviewer-agent	ja	Paket, Konfiguration, Token, gepufferte Daten
Installer mit --uninstall	ja	führt den Paketmanager wie oben aus
cloudviewer-agent uninstall	ja	Konfiguration, Token, gepufferte Daten; das Paket bleibt
Server entfernen im Portal	entfernt ihn aus der Überwachung	nichts; sein Token funktioniert nicht mehr
helm uninstall cloudviewer-agent	nein	das DaemonSet
Löschen eines per Flotte registrierten Cloud-Servers über die Hetzner API	automatisch außer Dienst gestellt	entfällt

Die Abmeldung geschieht nach bestem Bemühen. Schlägt der Aufruf fehl, sagt der Befehl das; prüf dann das Portal und entferne den Server dort, wenn er nicht Außer Dienst zeigt. Ein außer Dienst gestellter Server gibt seinen Platz im Plan sofort frei.

Was installiert bleibt:

• Debian, Ubuntu: das Paket vector, /etc/apt/sources.list.d/cloudviewer.list und vector.list sowie die Schlüssel in /usr/share/keyrings/. Nutzt du Vector sonst nicht, führ apt autoremove aus und lösch die beiden List-Dateien.
• RHEL-Familie: /etc/yum.repos.d/cloudviewer.repo und vector.repo. dnf entfernt vector normalerweise zusammen mit dem Agent.
• Der Systemnutzer cloudviewer-agent.

Prüfen, was installiert ist

dpkg -L cloudviewer-agent && dpkg --verify cloudviewer-agent   # Debian, Ubuntu
rpm -ql cloudviewer-agent && rpm -V cloudviewer-agent          # RHEL-Familie

Der erste Befehl listet jede Datei des Pakets, der zweite meldet Dateien, die sich seit der Installation geändert haben. Token, Parameter und Puffer in /etc/cloudviewer-agent/ und /var/lib/cloudviewer-agent/ gehören nicht zum Paket.

Container

Für Hosts ohne apt, dnf oder systemd:

docker run -d --name cloudviewer-agent --restart always \
  -e CV_AGENT_TOKEN=<agent_token> \
  -v /proc:/host/proc:ro -v /sys:/host/sys:ro -v /:/host/root:ro \
  -e PROCFS_ROOT=/host/proc -e SYSFS_ROOT=/host/sys \
  ghcr.io/cloudviewer-app/cloudviewer-agent:<version>

Variable	Bedeutung
CV_AGENT_TOKEN, CV_AGENT_TOKEN_FILE	Agent-Token pro Server oder eine Datei, die es enthält
CV_AGENT_ENROLL_TOKEN, CV_AGENT_ENROLL_TOKEN_FILE	Registrierungs-Token für die Flotte, nur Hetzner Cloud; der Container muss den Metadaten-Dienst erreichen
CV_AGENT_FACADE_URL	Basis-URL der Vaicoa API. Standard https://api.vaicoa.com

Der Container prüft wie das Paket alle 60 Sekunden auf neue Parameter. Ein falsches oder entzogenes Token stoppt ihn mit einer Meldung in seinem Log.

Kubernetes

Chart	oci://ghcr.io/cloudviewer-app/charts/cloudviewer-agent
Aufbau	Ein DaemonSet: ein Pod pro Node, hostNetwork, read-only Mounts von /proc, /sys und / des Nodes
Zugangsdaten	Ein Secret mit dem Schlüssel enroll-token (ein Flotten-Token, für Cluster) oder token (ein Token pro Server, nur für Single-Node-Cluster: Ein Token auf mehreren Nodes meldet sie alle als denselben Server). Gibt es beide, gewinnt token
Values	existingSecret, enrollToken, token, facadeUrl, image.repository, image.tag, image.digest, image.pullPolicy, resources, tolerations, nodeSelector, podAnnotations, priorityClassName
Berechtigungen	Kein ServiceAccount und kein RBAC; der Pod spricht nur mit Vaicoa
Nodes außerhalb der Hetzner Cloud	Können kein Flotten-Token nutzen; ihre Pods starten mit einer Meldung neu, die das sagt
Entfernen	helm uninstall cloudviewer-agent meldet die Nodes nicht ab. Nodes, die aus dem Hetzner-Projekt gelöscht werden, gehen von selbst außer Dienst; die anderen entfernst du im Portal

Details: die Chart-README.