> ## 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.

# Migrazione a `agenteye-collector`

> Documentazione di AgentEye per la migrazione a `agenteye-collector`.

La migrazione è non-distruttiva: non comporta downtime e non comporta perdita di dati, e libera il breve nome `agenteye` per la [CLI AgentEye](/it/agenteye/cli) in modo che il daemon collector e la CLI possono coesistere sulla stessa macchina.

Il binario del collector è stato **rinominato da `agenteye` a `agenteye-collector`**. Il breve nome `agenteye` ora appartiene alla CLI AgentEye, uno strumento separato per interrogare sessioni, eventi e valutazioni dal tuo terminale.

Questa guida ti accompagna attraverso la migrazione di un'installazione collector esistente.

***

## Cosa è cambiato

|                                        | Prima                                                                       | Dopo                                                                                                              |
| -------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Comando / binario                      | `agenteye`                                                                  | `agenteye-collector`                                                                                              |
| Percorso di installazione predefinito  | `/usr/local/bin/agenteye`                                                   | `/usr/local/bin/agenteye-collector`                                                                               |
| Sottocomandi                           | `start`, `flush`, `health`, `update`                                        | `start`, `flush`, `health`                                                                                        |
| Auto-aggiornamento (`agenteye update`) | integrato                                                                   | **rimosso**: scarica il nuovo binario o tira la nuova immagine                                                    |
| Script di installazione (`install.sh`) | fornito                                                                     | **rimosso**: scarica il binario direttamente (vedi [Collector Installation](/it/agenteye/collector-installation)) |
| `AGENTEYE_TOKEN`                       | necessario per scaricare **e** per controlli di aggiornamento in background | necessario solo per **scaricare** binari/immagini                                                                 |

La configurazione è invariata: lo stesso `~/.agenteye/config.json`, le stesse variabili d'ambiente `AGENTEYE_URL` / `AGENTEYE_KEY` / `AGENTEYE_HOME` / TLS, e lo stesso spool `~/.agenteye/events/`. **Non sono richieste modifiche di configurazione.**

> Se esegui il binario rinominato con il vecchio nome `agenteye`, funziona comunque ma stampa un avviso di deprecazione su una riga su stderr ricordandoti di passare a `agenteye-collector`.

***

## Prima di iniziare

* La tua **installazione `agenteye` esistente continua a funzionare**; nulla si rompe nel momento in cui aggiorni. Esegui la migrazione deliberatamente, poi rimuovi il vecchio binario per ultimo.
* Segui questo ordine per evitare downtime:
  1. Installa il nuovo binario `agenteye-collector` (o tira la nuova immagine).
  2. Aggiorna la tua definizione di servizio / health probe / script per chiamare `agenteye-collector`.
  3. Ricarica e riavvia il servizio; conferma che sia in salute.
  4. **Solo allora** rimuovi il vecchio binario `/usr/local/bin/agenteye`.

***

## 1. Installa il nuovo binario

Scarica l'artefatto per la tua piattaforma (`agenteye-collector-linux-x86_64`, `agenteye-collector-darwin-arm64`, e così via; vedi [Collector Installation → Option A](/it/agenteye/collector-installation#option-a-binary-recommended) per l'elenco completo) dall'ultima release `collector/v<version>` e posizionalo in `/usr/local/bin/agenteye-collector`. Utenti Docker: `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest` (o un tag `:v<version>` fisso, che è preferibile; `:latest` esiste solo per release stabili).

Verifica:

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

***

## 2. Aggiorna il tuo deployment

### systemd (Linux)

Modifica `/etc/systemd/system/agenteye-collector.service` in modo che `ExecStart` punti al nuovo binario:

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

Quindi ricarica e riavvia:

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

### launchd (macOS)

> **Cambio di marca:** Se il tuo plist esistente si trova nel percorso più vecchio
> `~/Library/LaunchAgents/host.exosphere.agenteye-collector.plist`, rinomina
> il file in `ai.befailproof.agenteye-collector.plist` e cambia anche il
> valore `<key>Label</key>` all'interno del file al nuovo identificatore prima
> di ricaricare.

In `~/Library/LaunchAgents/ai.befailproof.agenteye-collector.plist`, cambia la prima voce `ProgramArguments` da `/usr/local/bin/agenteye` a `/usr/local/bin/agenteye-collector`, quindi ricarica:

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

### supervisord

Nel tuo blocco programma `supervisord`, imposta `command` al nuovo binario:

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

Quindi `supervisorctl reread && supervisorctl update`.

### Docker / Kubernetes

Tira la nuova immagine (`ghcr.io/agenteye-enterprise/collector:beta-latest` o un tag `:v<version>` fisso, che è preferibile; `:latest` esiste solo per release stabili). L'entrypoint dell'immagine è già `agenteye-collector`, quindi lo stesso comando `docker run` con il sottocomando `start` continua a funzionare senza modifiche.

**Importante: aggiorna gli health probe.** Se usi una probe liveness/readiness di Kubernetes (o qualsiasi `docker exec`) che esegue il binario per nome, cambia il comando in `agenteye-collector`:

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

La nuova immagine **non** fornisce un alias `agenteye`, quindi una probe che chiama ancora `agenteye` fallirà. Aggiorna la probe nello stesso rollout della nuova immagine.

### Cron / script manuali

Sostituisci qualsiasi invocazione `agenteye start|flush|health` con il comando `agenteye-collector start|flush|health` corrispondente. **Elimina qualsiasi cron job `agenteye update`**; quel sottocomando non esiste più (vedi [Upgrades from now on](#upgrades-from-now-on)).

***

## 3. Rimuovi il vecchio binario (per ultimo)

Una volta che il servizio funziona su `agenteye-collector` e segnala buone condizioni:

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

Questo è importante soprattutto se usi anche la CLI AgentEye, che installa il suo proprio comando `agenteye`; lasciare il vecchio binario del collector in `/usr/local/bin/agenteye` renderebbe il nome `agenteye` ambiguo nel tuo `PATH`.

***

## Aggiornamenti da ora in poi

Il collector non si aggiorna più da solo. Per aggiornare:

* **Binario:** scarica il nuovo artefatto per la tua piattaforma (ad esempio `agenteye-collector-linux-x86_64`; vedi [Collector Installation → Option A](/it/agenteye/collector-installation#option-a-binary-recommended) per l'elenco completo), sostituisci `/usr/local/bin/agenteye-collector` e riavvia il servizio.
* **Docker:** `docker pull ghcr.io/agenteye-enterprise/collector:beta-latest` (o un tag `:v<version>` fisso, che è preferibile; `:latest` esiste solo per release stabili) e ricrea il container.

`AGENTEYE_TOKEN` è ancora necessario per scaricare dal repo delle release private, ma il daemon in esecuzione non ne ha più bisogno.

***

## Verifica

```bash theme={null}
agenteye-collector --version    # nuovo binario è nel PATH
agenteye-collector health       # exit 0 = in salute
agenteye-collector flush        # inoltri gli eventi in coda e termina in modo pulito
```

Quindi conferma che i nuovi eventi appaiono nel tuo dashboard.

***

## Rollback

La migrazione è non-distruttiva. Se hai bisogno di eseguire il rollback, fai puntare la tua definizione di servizio di nuovo al vecchio binario `/usr/local/bin/agenteye` (purché non l'abbia ancora rimosso) e riavvia. Lo spool degli eventi e la configurazione sono condivisi e non sono interessati.

***

## Risoluzione dei problemi

| Sintomo                                                                        | Causa                                                          | Soluzione                                                                                                                  |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `warning: the collector binary is now agenteye-collector …` ad ogni esecuzione | Stai invocando il binario con il vecchio nome `agenteye`       | Chiama `agenteye-collector` invece; aggiorna file di servizio e script.                                                    |
| systemd fallisce: `.../agenteye: No such file or directory`                    | Hai rimosso il vecchio binario prima di aggiornare `ExecStart` | Imposta `ExecStart=/usr/local/bin/agenteye-collector start`, quindi `sudo systemctl daemon-reload`.                        |
| Il pod Kubernetes va in crash-loop dopo l'aggiornamento dell'immagine          | Il probe liveness esegue ancora `agenteye`                     | Cambia il comando del probe in `["agenteye-collector", "health"]`.                                                         |
| `agenteye: command not found`, ma `agenteye-collector` funziona                | Script/alias fanno ancora riferimento al vecchio nome          | Aggiornali a `agenteye-collector`.                                                                                         |
| L'esecuzione di `agenteye` avvia la CLI, non il collector                      | Hai la CLI AgentEye installata; possiede `agenteye`            | Usa `agenteye-collector` per il daemon e rimuovi qualsiasi vecchio binario collector rimasto in `/usr/local/bin/agenteye`. |