Il gateway di Chatcode
Cos'è il gateway di Chatcode, dove gira (Linux o macOS), come comunica con Chatcode, i compromessi di fiducia e perché macOS mostra richieste di autorizzazione.
Il gateway è il piccolo programma che fa funzionare Chatcode su una macchina tua. Esegue i tuoi agenti di coding (Claude Code, Codex, Gemini, OpenCode) e li collega al browser su app.chatcode.dev e a Telegram, senza esporre nulla in ingresso sulla tua macchina.
Questa pagina spiega in parole semplici cos’è, dove si trova, come comunica con Chatcode e quali compromessi di fiducia comporta, compreso il motivo per cui macOS a volte mostra richieste di autorizzazione dall’aspetto allarmante (in breve: è il tuo agente che fa ciò che gli hai chiesto).
Cos’è il gateway
- Un unico binario,
chatcode-gateway(compilato per ogni piattaforma: Linux/macOS × Intel/ARM), installato come servizio in background. - Mantiene una sola connessione in uscita verso il piano di controllo di Chatcode ed esegue le sessioni dei tuoi agenti in workspace
tmuxdentro~/workspace. - È il riquadro «Il tuo server + gateway» nell’architettura di Chatcode: browser ⇄ Chatcode ⇄ il tuo gateway ⇄ sessione dell’agente.
- Il binario della release viene scaricato via HTTPS e verificato tramite checksum (SHA-256) prima di essere installato.
Dove gira: Linux o macOS
Il gateway usa due modelli diversi a seconda del sistema operativo: è la differenza pratica più importante.
Linux: un utente dedicato vibe (isolato)
È il modello usato dai droplet DigitalOcean della modalità facile e dai server Linux che colleghi tu. L’installer viene eseguito come root e:
- Crea un utente dedicato
vibe(gli agenti girano comevibe, non con il tuo account di accesso) con il proprio workspace in/home/vibe/workspace. - Installa un servizio systemd (
chatcode-gateway.service) che gira comevibe. - Installa gli strumenti di base, tra cui
tmux,git,ripgrepebubblewrap(per isolare in sandbox le sessioni degli agenti). - Preinstalla Claude Code e Codex e attiva un timer di manutenzione giornaliero che aggiorna le CLI degli agenti e il gateway stesso.
Dato che gli agenti girano con un utente tutto loro, su quella macchina sono isolati dal tuo account personale e dai tuoi file.
macOS: il tuo utente
È il modello usato quando colleghi un tuo Mac. L’installer viene eseguito con il tuo utente normale (mai con sudo) e:
- Installa il binario in
~/.local/bin/chatcode-gatewaye un agente launchd (dev.chatcode.gateway) che si avvia al login e resta in esecuzione (sui Mac desktop viene tenuto sveglio concaffeinate). - Richiede Homebrew, oltre a
tmux,gitecurl.
Qui l’agente gira con il tuo utente, quindi ha i tuoi stessi accessi ai file. È comodo, ed è proprio il motivo per cui macOS mostra le richieste di autorizzazione descritte più avanti.
Dove si trova cosa
| Linux (gestito) | macOS (il tuo utente) | |
|---|---|---|
| Binario | /usr/local/bin/chatcode-gateway |
~/.local/bin/chatcode-gateway |
| Servizio | systemd chatcode-gateway.service |
launchd dev.chatcode.gateway |
| Configurazione/env | /etc/chatcode/gateway.env (permessi 600) |
~/.config/chatcode/gateway.env (permessi 600) |
| Gira come | utente dedicato vibe |
il tuo utente di login |
| Workspace | /home/vibe/workspace |
~/workspace |
| Log | journalctl -u chatcode-gateway |
~/Library/Logs/chatcode-gateway.log |
Installazione
Nell’app, aggiungi un server e Chatcode ti dà un comando pronto da eseguire, con l’ID del gateway, il token di autenticazione e l’URL del piano di controllo già compilati. Il comando passa alla tua shell l’installer ufficiale su https://chatcode.dev/install.sh (che reindirizza all’ultima release):
# Linux — run as root (installs under a dedicated `vibe` user)
curl -fsSL https://chatcode.dev/install.sh | sudo bash -s -- \
--gateway-id gw_xxx --gateway-auth-token tok_xxx \
--cp-url wss://<control-plane>/gw/connect
# macOS — run as your normal user (do NOT use sudo)
curl -fsSL https://chatcode.dev/install.sh | bash -s -- \
--gateway-id gw_xxx --gateway-auth-token tok_xxx \
--cp-url wss://<control-plane>/gw/connect
L’installer scarica il binario del gateway da releases.chatcode.dev e ne verifica il checksum SHA-256 prima di installarlo. Puoi fissare una versione (--version vX.Y.Z) invece di seguire latest, oppure compilare tu il binario e installarlo con --binary-source /path/to/chatcode-gateway.
Sudo senza password (e come resta verificabile)
Quando un agente che stai usando deve compiere un’azione amministrativa, come installare un pacchetto o riavviare un servizio, non può fermarsi a chiederti una password tramite Telegram. Per questo il gateway è configurato per l’amministrazione non presidiata:
- Linux: l’utente
vibeha sudoNOPASSWD, ma ogni comando viene registrato (use_pty) in un log di proprietà di root e di sola aggiunta (append-only) in/var/log/chatcode/sudo-vibe.log, chevibepuò leggere ma non modificare, con rotazione su 14 giorni. Puoi verificare esattamente cosa è stato eseguito. - macOS: il sudo senza password è facoltativo e viene proposto solo se scegli di attivarlo durante l’installazione. Se lo rifiuti, il gateway funziona comunque: ti verrà semplicemente chiesta la password (oppure le attività amministrative non verranno eseguite), come su qualsiasi Mac normale.
È un compromesso voluto per avere un sistema che «funziona mentre non ci sei», reso verificabile anziché nascosto.
Richieste di autorizzazione di macOS: niente panico
Se esegui il gateway sul tuo Mac, probabilmente vedrai richieste di macOS come questa:
«chatcode-gateway» vorrebbe accedere ai file nella cartella Documenti.
…oppure richieste che riguardano Scrivania, Download, i volumi rimovibili, Accessibilità o Registrazione schermo. Possono sembrare allarmanti, come se il gateway volesse curiosare tra i tuoi dati. Non è così.
Ecco cosa succede davvero: su macOS il gateway gira con il tuo utente ed esegue l’agente che hai chiesto tu. Quando quell’agente legge un file in una cartella protetta, o quando uno strumento che avvia deve automatizzare l’interfaccia o catturare lo schermo, interviene il sistema di privacy di macOS (TCC), che chiede il consenso e attribuisce la richiesta al processo che ha avviato il lavoro, cioè chatcode-gateway. Quindi nella finestra di dialogo compare il nome del gateway, ma dietro c’è il tuo agente che svolge il compito che gli hai dato.
Cosa fare:
- Consenti ciò che ti aspetti. Se hai chiesto all’agente di lavorare con i file in
~/Documents, consentire l’accesso a Documenti è esattamente la scelta giusta. - Nega ciò che non ti aspetti. Il controllo resta sempre a te: negare significa solo che l’agente non può toccare quella risorsa.
- Gestisci tutto quando vuoi in Impostazioni di Sistema → Privacy e sicurezza (File e cartelle, Accessibilità, Registrazione schermo). Su un Mac in inglese: System Settings → Privacy & Security.
Su Linux non esiste una finestra equivalente: l’utente vibe ha semplicemente i propri permessi Unix, isolati dal tuo account.
Come comunica
Browser / Telegram ⇄ Chatcode control plane ⇄ your gateway ⇄ agent session
(you) (TLS relay) (your machine) (Claude/Codex/…)
- Il gateway si collega in uscita al piano di controllo tramite un WebSocket TLS (
wss://…). Non apre mai una porta in ingresso sulla tua macchina. - Il browser e Telegram si collegano al piano di controllo, che inoltra il traffico al tuo gateway.
- Tu ti autentichi con un cookie di sessione; il gateway si autentica con un token specifico per ciascun gateway. Il piano di controllo non archivia le tue chiavi SSH private.
Niente cifratura end-to-end: ecco perché
Tra il tuo browser e il gateway non c’è cifratura end-to-end, ed è una scelta progettuale voluta, non una svista. Ogni tratta è cifrata con TLS, ma il piano di controllo termina quelle connessioni per poter elaborare il contenuto della sessione che fa funzionare l’esperienza su Telegram: formattare l’output dell’agente per la chat, generare le anteprime dei file, trascrivere i messaggi vocali e decidere quando avvisarti. Questa elaborazione richiede payload leggibili, quindi il piano di controllo si trova in una posizione di nodo di inoltro fidato e può leggere il traffico del terminale.
Preferiamo dirlo chiaramente piuttosto che lasciar intendere una garanzia che non offriamo. Il tuo codice, le tue credenziali e le sessioni dei tuoi agenti restano comunque solo sulla tua macchina. Se vuoi tenere sotto il tuo controllo anche il nodo di inoltro, puoi ospitare tu stesso il piano di controllo nel tuo account Cloudflare.
Cosa mostra il gateway su Telegram
Telegram è il livello di continuità, e a servirlo è il gateway. Quando apri l’anteprima di un file da una chat, il gateway legge quel file e lo restituisce attraverso il nodo di inoltro. I limiti sono volutamente stretti:
- Sola lettura. Le anteprime non scrivono mai. A scrivere sono solo il lavoro delle sessioni e i caricamenti, confinati in
~/workspace. - Ambito limitato. Le anteprime sono limitate a
~/workspacepiù i percorsi non nascosti nella home dell’utente del gateway. Le cartelle nascoste come~/.ssh,~/.claudee~/.codexsono inaccessibili, a meno che non si trovino dentro~/workspace, e il controllo avviene sul percorso reale, con i link simbolici risolti, quindi non si può aggirare con un link simbolico. - Link di breve durata. Il download di un’anteprima usa un URL bearer senza cookie che scade dopo circa cinque minuti.
Un’avvertenza da dire chiaramente: la radice di lettura delle anteprime include i file non nascosti in qualsiasi punto della home dell’utente del gateway, quindi tieni i segreti fuori da quella directory home (su Linux è /home/vibe), non solo fuori dai dotfile.
Riepilogo su fiducia e privacy
- La tua macchina, il tuo abbonamento. Gli agenti girano su hardware tuo, con il tuo login Claude/ChatGPT. Chatcode è il nodo di inoltro, non un cloud che copia il tuo repository altrove.
- Nessuna porta in ingresso. Solo un WebSocket in uscita. L’accesso SSH per una sessione di debug è separato e lo abiliti tu (aggiungi tu una chiave; di default non ce n’è nessuna).
- Confine del workspace. Il lavoro delle sessioni e i caricamenti sono limitati a
~/workspace; le anteprime su Telegram sono in sola lettura e con ambito limitato (dettagli sopra). - Amministrazione verificabile. Su Linux il sudo senza password viene registrato in un file append-only di proprietà di root.
- Segreti a riposo. Il file env che contiene il token del tuo gateway ha i permessi
600.
Verifica cosa viene eseguito
Non devi crederci sulla parola:
- Leggi l’installer. È un semplice script di shell che esegui tu: esaminalo prima che tocchi la macchina.
- Verifica il checksum. Ogni release include un file
.sha256; l’installer lo controlla e puoi verificarlo di nuovo anche tu. - Fissa una versione con
--version vX.Y.Zinvece dilatest. - Compila dai sorgenti e installa con
--binary-source. - Ospita tu stesso il piano di controllo nel tuo account Cloudflare, per avere il pieno controllo del nodo di inoltro.
Stiamo documentando il protocollo del gateway e rendendo pubblica, nel tempo, una parte sempre maggiore del codice sorgente, così che il comportamento del nodo di inoltro e quello sulla macchina possano essere verificati in modo indipendente: è con la trasparenza che questo sistema si guadagna la fiducia.
Aggiornamento e disinstallazione
- Aggiornamento: un job di manutenzione giornaliero aggiorna automaticamente il gateway e le CLI degli agenti. Per aggiornare subito, esegui di nuovo l’installer con una
--versionpiù recente. - Stato / log:
systemctl status chatcode-gatewayejournalctl -u chatcode-gatewaysu Linux;~/Library/Logs/chatcode-gateway.logsu macOS. - Disinstallazione: esegui lo script di pulizia. È distruttivo per impostazione predefinita: leggilo prima.
# Linux — removes the service, config, sudoers + log policy, and the `vibe` user + home
curl -fsSL https://chatcode.dev/cleanup.sh | sudo bash -s -- --yes
# macOS — removes the launchd agents, binary, config, and Chatcode-managed hooks; keeps ~/workspace
curl -fsSL https://chatcode.dev/cleanup.sh | bash -s -- --yes
Opzioni utili: --keep-user (Linux: mantiene l’utente vibe e la sua home), --keep-workspace, --remove-workspace (macOS: elimina anche ~/workspace) e --kill-tmux. Su macOS ~/workspace viene mantenuto, a meno che tu non passi --remove-workspace.
Sei alle prime armi con tutto questo? Inizia da Come usare Claude Code su Telegram con Chatcode per avere il quadro generale della configurazione.
Domande frequenti
Mi serve un server mio per eseguire il gateway?
No. In modalità facile, Chatcode si collega a DigitalOcean e crea per te un droplet Linux su cui gira il gateway. Il percorso con un tuo server installa lo stesso gateway su un server Linux o su un Mac che possiedi già.
Perché macOS dice che chatcode-gateway vuole accedere a Documenti / Download / allo schermo?
Su macOS il gateway gira con il tuo utente, quindi l’agente di coding che stai usando (Claude Code, Codex, ecc.) ha i tuoi stessi accessi ai file. Quando quell’agente legge una cartella protetta o usa una funzionalità protetta, macOS mostra la sua consueta richiesta di privacy e la attribuisce al processo che ha avviato l’agente, cioè il gateway. È il tuo agente che fa ciò che gli hai chiesto, e macOS te lo segnala con il suo normale flusso di consenso. Consenti ciò che ti aspetti; nega ciò che non ti aspetti.
Il gateway apre porte sulla mia macchina?
Nessuna porta in ingresso. Il gateway apre una connessione WebSocket TLS in uscita verso il piano di controllo di Chatcode, e il piano di controllo inoltra il traffico dal tuo browser e da Telegram. (L’accesso SSH per una sessione di debug è separato e lo abiliti tu, se vuoi.)
Chatcode può vedere il traffico del mio terminale?
In transito, sì. Il traffico è cifrato con TLS su ogni tratta, ma tra il tuo browser e il gateway non c’è cifratura end-to-end, per scelta progettuale. Il piano di controllo elabora il contenuto della sessione per far funzionare l’esperienza su Telegram (formattazione dell’output dell’agente, anteprime dei file, trascrizione vocale, notifiche), quindi si trova in una posizione di nodo di inoltro fidato e può leggere i payload del terminale. Il tuo codice, le tue chiavi e le sessioni dei tuoi agenti restano comunque solo sulla tua macchina; per controllare anche il nodo di inoltro, ospitalo tu stesso.
Perché il gateway usa sudo senza password su Linux?
Così un agente che stai usando può svolgere attività amministrative (installare un pacchetto, riavviare un servizio) senza bloccarsi su una richiesta di password a cui non puoi rispondere da remoto. Su Linux gira con un utente dedicato vibe, e ogni comando sudo viene scritto in un log append-only di proprietà di root, che puoi consultare.