> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration zu `agenteye-collector`

> AgentEye-Dokumentation zur Migration zu `agenteye-collector`.

Die Migration ist nicht-destruktiv: Es gibt keine Ausfallzeiten und keinen Datenverlust. Außerdem wird der kurze Name `agenteye` für die [AgentEye CLI](/de/agenteye/cli) freigegeben, sodass der Collector-Daemon und die CLI auf demselben Rechner koexistieren können.

Das Collector-Binary wurde **von `agenteye` in `agenteye-collector` umbenannt**. Der kurze Name `agenteye` gehört nun zur AgentEye CLI, einem separaten Werkzeug zum Abfragen von Sessions, Events und Evaluierungen über das Terminal.

Diese Anleitung führt Sie durch die Migration einer bestehenden Collector-Installation.

***

## Was sich geändert hat

|                                    | Vorher                                                                  | Nachher                                                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Befehl / Binary                    | `agenteye`                                                              | `agenteye-collector`                                                                                            |
| Standard-Installationspfad         | `/usr/local/bin/agenteye`                                               | `/usr/local/bin/agenteye-collector`                                                                             |
| Unterbefehle                       | `start`, `flush`, `health`, `update`                                    | `start`, `flush`, `health`                                                                                      |
| Selbst-Update (`agenteye update`)  | eingebaut                                                               | **entfernt**: neues Binary herunterladen oder neues Image pullen                                                |
| Installationsskript (`install.sh`) | vorhanden                                                               | **entfernt**: Binary direkt herunterladen (siehe [Collector-Installation](/de/agenteye/collector-installation)) |
| `AGENTEYE_TOKEN`                   | zum Herunterladen **und** für Hintergrund-Update-Prüfungen erforderlich | nur zum **Herunterladen** von Binaries/Images erforderlich                                                      |

Die Konfiguration bleibt unverändert: dasselbe `~/.agenteye/config.json`, dieselben Umgebungsvariablen `AGENTEYE_URL` / `AGENTEYE_KEY` / `AGENTEYE_HOME` / TLS sowie derselbe `~/.agenteye/events/`-Spool. **Es sind keine Konfigurationsänderungen erforderlich.**

> Wenn Sie das umbenannte Binary unter dem alten Namen `agenteye` ausführen, funktioniert es weiterhin, gibt aber eine einzeilige Deprecation-Warnung auf stderr aus, die Sie auf den Wechsel zu `agenteye-collector` hinweist.

***

## Bevor Sie beginnen

* Ihre **bestehende `agenteye`-Installation läuft weiter**; beim Upgrade passiert sofort nichts. Führen Sie die Migration bewusst durch und entfernen Sie das alte Binary zuletzt.
* Halten Sie diese Reihenfolge ein, um Ausfallzeiten zu vermeiden:
  1. Das neue `agenteye-collector`-Binary installieren (oder das neue Image pullen).
  2. Ihre Service-Definition, Health-Probe und Skripte auf `agenteye-collector` umstellen.
  3. Den Service neu laden und starten; prüfen, ob er gesund ist.
  4. **Erst dann** das alte Binary `/usr/local/bin/agenteye` entfernen.

***

## 1. Das neue Binary installieren

Laden Sie das Artefakt für Ihre Plattform herunter (`agenteye-collector-linux-x86_64`, `agenteye-collector-darwin-arm64` usw.; die vollständige Liste finden Sie unter [Collector-Installation → Option A](/de/agenteye/collector-installation#option-a-binary-recommended)) aus dem neuesten `collector/v<version>`-Release und legen Sie es unter `/usr/local/bin/agenteye-collector` ab. Docker-Nutzer: `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest` (oder ein gepinnter `:v<version>`-Tag, was bevorzugt wird; `:latest` existiert nur für stabile Releases).

Überprüfung:

```bash theme={null}
agenteye-collector --version
```

***

## 2. Ihr Deployment aktualisieren

### systemd (Linux)

Bearbeiten Sie `/etc/systemd/system/agenteye-collector.service`, sodass `ExecStart` auf das neue Binary zeigt:

```ini theme={null}
[Service]
ExecStart=/usr/local/bin/agenteye-collector start
```

Dann neu laden und neu starten:

```bash theme={null}
sudo systemctl daemon-reload
sudo systemctl restart agenteye-collector
sudo systemctl status agenteye-collector
```

### launchd (macOS)

> **Brand-Umbenennung:** Wenn Ihre bestehende Plist-Datei unter dem älteren Pfad
> `~/Library/LaunchAgents/host.exosphere.agenteye-collector.plist` liegt, benennen Sie
> die Datei in `ai.befailproof.agenteye-collector.plist` um und ändern Sie außerdem den
> `<key>Label</key>`-Wert in der Datei auf den neuen Bezeichner, bevor Sie sie neu laden.

Ändern Sie in `~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist` den ersten `ProgramArguments`-Eintrag von `/usr/local/bin/agenteye` auf `/usr/local/bin/agenteye-collector` und laden Sie dann neu:

```bash theme={null}
launchctl unload ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist
launchctl load   ~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist
```

### supervisord

Setzen Sie in Ihrem `supervisord`-Programmblock `command` auf das neue Binary:

```ini theme={null}
[program:agenteye-collector]
command=/usr/local/bin/agenteye-collector start
```

Dann `supervisorctl reread && supervisorctl update`.

### Docker / Kubernetes

Pullen Sie das neue Image (`ghcr.io/agenteye-enterprise/collector:beta-latest` oder ein gepinnter `:v<version>`-Tag, was bevorzugt wird; `:latest` existiert nur für stabile Releases). Der Image-Entrypoint ist bereits `agenteye-collector`, sodass derselbe `docker run`-Befehl mit dem `start`-Unterbefehl ohne Änderungen weiterhin funktioniert.

**Wichtig: Health-Probes aktualisieren.** Wenn Sie eine Kubernetes-Liveness/Readiness-Probe (oder ein `docker exec`) verwenden, das das Binary namentlich aufruft, ändern Sie den Befehl auf `agenteye-collector`:

```yaml theme={null}
livenessProbe:
  exec:
    command: ["agenteye-collector", "health"]
```

Das neue Image liefert **keinen** `agenteye`-Alias, sodass eine Probe, die weiterhin `agenteye` aufruft, fehlschlägt. Aktualisieren Sie die Probe im selben Rollout wie das neue Image.

### Cron / manuelle Skripte

Ersetzen Sie alle `agenteye start|flush|health`-Aufrufe durch den entsprechenden `agenteye-collector start|flush|health`-Befehl. **Löschen Sie alle `agenteye update`-Cron-Jobs**; dieser Unterbefehl existiert nicht mehr (siehe [Zukünftige Upgrades](#upgrades-from-now-on)).

***

## 3. Das alte Binary entfernen (zuletzt)

Sobald der Service auf `agenteye-collector` läuft und als gesund gemeldet wird:

```bash theme={null}
sudo rm /usr/local/bin/agenteye
```

Dies ist besonders wichtig, wenn Sie auch die AgentEye CLI verwenden, die ihren eigenen `agenteye`-Befehl installiert; das alte Collector-Binary unter `/usr/local/bin/agenteye` zu belassen würde den Namen `agenteye` auf Ihrem `PATH` mehrdeutig machen.

***

## Zukünftige Upgrades

Der Collector aktualisiert sich nicht mehr selbst. Für Upgrades gilt:

* **Binary:** Laden Sie das neue Artefakt für Ihre Plattform herunter (z. B. `agenteye-collector-linux-x86_64`; die vollständige Liste finden Sie unter [Collector-Installation → Option A](/de/agenteye/collector-installation#option-a-binary-recommended)), ersetzen Sie `/usr/local/bin/agenteye-collector` und starten Sie den Service neu.
* **Docker:** `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest` (oder ein gepinnter `:v<version>`-Tag, was bevorzugt wird; `:latest` existiert nur für stabile Releases) und den Container neu erstellen.

`AGENTEYE_TOKEN` ist weiterhin erforderlich, um aus dem privaten Release-Repository herunterzuladen, aber der laufende Daemon benötigt ihn nicht mehr.

***

## Überprüfung

```bash theme={null}
agenteye-collector --version    # neues Binary ist im PATH
agenteye-collector health       # Exit 0 = gesund
agenteye-collector flush        # leert alle gepufferten Events und beendet sich sauber
```

Prüfen Sie dann, ob neue Events in Ihrem Dashboard erscheinen.

***

## Rollback

Die Migration ist nicht-destruktiv. Falls Sie ein Rollback benötigen, verweisen Sie Ihre Service-Definition zurück auf das alte Binary `/usr/local/bin/agenteye` (solange Sie es noch nicht entfernt haben) und starten Sie den Service neu. Der Event-Spool und die Konfiguration werden gemeinsam genutzt und sind nicht betroffen.

***

## Fehlerbehebung

| Symptom                                                                      | Ursache                                                              | Lösung                                                                                                                    |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `warning: the collector binary is now agenteye-collector …` bei jedem Aufruf | Das Binary wird unter dem alten Namen `agenteye` aufgerufen          | Stattdessen `agenteye-collector` verwenden; Service-Dateien und Skripte aktualisieren.                                    |
| systemd schlägt fehl: `.../agenteye: No such file or directory`              | Das alte Binary wurde entfernt, bevor `ExecStart` aktualisiert wurde | `ExecStart=/usr/local/bin/agenteye-collector start` setzen, dann `sudo systemctl daemon-reload`.                          |
| Kubernetes-Pod crasht nach dem Image-Upgrade in einer Schleife               | Liveness-Probe ruft weiterhin `agenteye` auf                         | Probe-Befehl auf `["agenteye-collector", "health"]` ändern.                                                               |
| `agenteye: command not found`, aber `agenteye-collector` funktioniert        | Skripte/Aliases referenzieren noch den alten Namen                   | Diese auf `agenteye-collector` aktualisieren.                                                                             |
| Das Ausführen von `agenteye` startet die CLI, nicht den Collector            | Die AgentEye CLI ist installiert; sie besitzt `agenteye`             | `agenteye-collector` für den Daemon verwenden und veraltete Collector-Binaries unter `/usr/local/bin/agenteye` entfernen. |