L'app non installa né autentica i motori: lancia quelli che trova nel PATH, già installati e con l'accesso fatto ([ADR-0002](adr/0002-motori-cli-claude-codex-antigravity.md)). Questa pagina spiega come prepararli. Fonti e data di consultazione in fondo.
## Prima di iniziare: un ambiente, un motore
Il motore va installato **nello stesso ambiente in cui gira l'app**:
Dentro WSL il PATH di Windows è visibile (compare `/mnt/c/…`): se in WSL non c'è un `claude`, `codex` o `agy`, il comando può risolvere nella versione Windows. Controllalo con `command -v claude`, `command -v codex` e `command -v agy`.
**Requisiti**: macOS 13+, Windows 10 1809+ o Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine 3.19+; 4 GB di RAM, x64 o ARM64, connessione a internet. Su Windows nativo [Git for Windows](https://git-scm.com/downloads/win) è consigliato ma facoltativo.
**Installazione** (una delle opzioni; la prima è la raccomandata):
**Da zero su Linux, anche ARM64 (per esempio Raspberry Pi 5 con Raspberry Pi OS a 64 bit).** Il metodo nativo riconosce da solo l'architettura (`uname -m` deve dare `aarch64` o `x86_64`):
```
sudo apt install -y curl # se manca
curl -fsSL https://claude.ai/install.sh | bash
# apri un nuovo terminale, poi:
command -v claude # atteso: ~/.local/bin/claude
claude --version
claude # primo avvio: accesso nel browser
```
Su un Raspberry senza schermo l'accesso nel browser si fa da un altro dispositivo, seguendo l'indirizzo che `claude` stampa nel terminale (per esempio via SSH); in alternativa usa una API key o un provider cloud, vedi "Accesso". Se `~/.local/bin` non è nel PATH aggiungi `export PATH="$HOME/.local/bin:$PATH"` a `~/.bashrc`. Con la sola architettura ARM64 e Debian 10+ i requisiti sono soddisfatti; il metodo npm è l'alternativa se lo script nativo non funziona. Non provato su un Raspberry reale: le istruzioni vengono dalla guida ufficiale.
**Accesso**: esegui `claude` e segui le istruzioni nel browser. Serve un account Pro, Max, Team, Enterprise o Console (il piano gratuito di claude.ai non include Claude Code). In alternativa Amazon Bedrock, Google Cloud o Microsoft Foundry.
**Verifica**
```
claude --version # stampa la versione, es. 2.1.x (Claude Code)
claude doctor # diagnostica di installazione e impostazioni
claude auth status # mostra se hai fatto l'accesso
```
**Aggiornamento**: l'installazione nativa si aggiorna da sola; `claude update` forza l'aggiornamento. Homebrew, WinGet, npm e i gestori di pacchetti vanno aggiornati a mano (`npm install -g @anthropic-ai/claude-code@latest`, evitando `npm update -g`).
## Codex CLI
**Requisiti**: macOS (Apple Silicon e Intel), Linux (x86_64 e arm64), Windows tramite lo script PowerShell. Per l'installazione con npm serve Node.js. Serve un piano ChatGPT (Plus, Pro, Business, Edu o Enterprise) oppure una API key.
| Binario | archivio dalla pagina delle release su GitHub (`openai/codex`), estratto e rinominato `codex` |
Gli script scaricano da `releases.openai.com` e, se fallisce, da GitHub Releases; per forzare GitHub imposta `CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false`.
**Su Windows preferisci lo script PowerShell a npm.** L'app avvia l'eseguibile direttamente, senza `cmd.exe /c`; un'installazione con npm potrebbe produrre uno script `.cmd` che così non parte (rischio indicato nell'ADR-0002, da verificare su Windows).
**Accesso**: esegui `codex` e scegli "Sign in with ChatGPT" (consigliato), oppure usa una API key (guida ufficiale: sezione autenticazione).
**Verifica**
```
codex --version # es. codex-cli 0.144.x
codex login status # "Logged in using ChatGPT" se l'accesso è fatto
codex exec --help # uso non interattivo, usato dall'app
```
**Stato su questa macchina** (WSL, controllato il 2026-10-15): `codex` 0.144.3 in `~/.local/bin/codex`, collegamento a `~/.codex/packages/standalone/current/bin/codex`, con accesso ChatGPT già fatto. `claude` 2.1.252 in `~/.npm-global/bin/claude`, con accesso claude.ai già fatto.
**Problema noto: "requires a newer version of Codex".** Se il modello predefinito del tuo `~/.codex/config.toml` richiede un Codex più recente, `codex exec` fallisce con quell'errore (l'app lo mostra nella chat). Aggiorna con `codex update`, oppure scegli un altro modello nelle Impostazioni dell'app. Controllato su questa macchina il 2026-10-15 con Codex 0.144.3.
**Requisiti**: Linux x64 (binario nativo ELF) o Windows x64 (eseguibile nativo `.exe`).
**Installazione**: binario nativo distribuito ufficialmente (su Linux collocato in `~/.gemini/bin/agy` o in una cartella inclusa nel PATH; su Windows `agy.exe`).
**Accesso**: autenticazione tramite account Google/Antigravity (`agy` o configurazione di ambiente).
**Verifica**
```
agy --version # stampa la versione, es. 1.4.2
agy models # catalogo modelli disponibili
agy update # controlla e aggiorna alla versione più recente
**Permessi per la sola lettura non interattiva**: per usare `agy` in modalità non interattiva (`-p`) in sola lettura, nel file `~/.gemini/antigravity-cli/settings.json` deve essere presente la regola `'read_file(*)'` sotto `'permissions.allow'` (altrimenti headless mode nega `read_file` con errore jetski: `a tool required the read_file permission that headless mode cannot prompt for`), mentre scritture e comandi restano negati di default:
Nel riquadro Impostazioni, sezione **Aggiornamenti**, l'app controlla da sola, all'avvio e all'apertura del riquadro, se c'è una versione più recente (Claude Code: `downloads.claude.ai`; Codex: release di GitHub; Antigravity: endpoint ufficiale di auto-update): se c'è, la riga dice "Aggiornamento disponibile", il pulsante **Aggiorna** si evidenzia e compare un puntino sul pulsante Impostazioni. Il pulsante esegue `claude update`, `codex update` o `agy update` (controllano e installano solo se c'è una versione nuova). Nulla si aggiorna senza un clic. Se non va a buon fine l'app mostra l'errore e il comando manuale, che dipende da come hai installato il CLI:
| Installazione | Claude Code | Codex | Antigravity |
