Passerelle

La passerelle Chatcode

La passerelle Chatcode : son rôle, où elle tourne (Linux ou macOS), ses échanges avec Chatcode, ses compromis de confiance et pourquoi macOS demande votre accord.

La passerelle est le petit programme qui fait fonctionner Chatcode sur une machine qui vous appartient. Elle exécute vos agents de codage (Claude Code, Codex, Gemini, OpenCode) et les relie au navigateur, sur app.chatcode.dev, ainsi qu’à Telegram, sans exposer votre machine au moindre accès entrant.

Cette page explique simplement ce qu’elle est, où elle se trouve, comment elle communique avec Chatcode et quels compromis de confiance elle implique, y compris pourquoi macOS affiche parfois des demandes d’autorisation à l’air inquiétant (en bref : c’est votre agent qui fait ce que vous lui avez demandé).

Ce qu’est la passerelle

  • Un binaire unique, chatcode-gateway (compilé pour chaque plateforme : Linux/macOS × Intel/ARM), installé comme service d’arrière-plan.
  • Elle maintient une seule connexion sortante vers le plan de contrôle de Chatcode et exécute vos sessions d’agent dans des espaces de travail tmux sous ~/workspace.
  • C’est le bloc « Your server + gateway » de l’architecture de Chatcode : navigateur ⇄ Chatcode ⇄ votre passerelle ⇄ session d’agent.
  • Le binaire de chaque version publiée est téléchargé en HTTPS et sa somme de contrôle (SHA-256) est vérifiée avant l’installation.

Où elle s’exécute : Linux ou macOS

La passerelle suit deux modèles différents selon le système d’exploitation ; c’est la principale différence en pratique.

Linux : un utilisateur dédié vibe (isolé)

C’est le modèle des droplets DigitalOcean du mode facile et des serveurs Linux que vous connectez vous-même. Le programme d’installation s’exécute en tant que root et :

  • Crée un utilisateur dédié vibe (les agents s’exécutent en tant que vibe, et non sous votre compte de connexion), avec son espace de travail dans /home/vibe/workspace.
  • Installe un service systemd (chatcode-gateway.service) qui s’exécute en tant que vibe.
  • Installe des outils de base, dont tmux, git, ripgrep et bubblewrap (pour isoler les sessions d’agent dans un bac à sable).
  • Préinstalle Claude Code et Codex, et active un minuteur de maintenance quotidien qui met à jour les CLI des agents et la passerelle elle-même.

Comme les agents s’exécutent sous leur propre utilisateur, ils sont isolés de votre compte personnel et de vos fichiers sur cette machine.

macOS : votre propre utilisateur

C’est le modèle utilisé lorsque vous connectez votre propre Mac. Le programme d’installation s’exécute sous votre utilisateur habituel (jamais avec sudo) et :

  • Installe le binaire dans ~/.local/bin/chatcode-gateway ainsi qu’un agent launchd (dev.chatcode.gateway) qui démarre à l’ouverture de session et reste actif (maintenu éveillé avec caffeinate sur les Mac de bureau).
  • Nécessite Homebrew ainsi que tmux, git et curl.

Ici, l’agent s’exécute sous votre compte : il a donc les mêmes accès aux fichiers que vous. C’est pratique, et c’est pour cette raison que macOS affiche les demandes d’autorisation décrites plus bas.

Où se trouve chaque élément

Linux (géré) macOS (votre utilisateur)
Binaire /usr/local/bin/chatcode-gateway ~/.local/bin/chatcode-gateway
Service systemd chatcode-gateway.service launchd dev.chatcode.gateway
Configuration/env /etc/chatcode/gateway.env (mode 600) ~/.config/chatcode/gateway.env (mode 600)
S’exécute sous utilisateur dédié vibe votre utilisateur de connexion
Espace de travail /home/vibe/workspace ~/workspace
Journaux journalctl -u chatcode-gateway ~/Library/Logs/chatcode-gateway.log

Installation

Dans l’application, ajoutez un serveur : Chatcode vous fournit une commande prête à l’emploi, avec l’identifiant de votre passerelle, votre token d’authentification et l’URL du plan de contrôle déjà renseignés. Elle télécharge le programme d’installation de référence, https://chatcode.dev/install.sh (qui redirige vers la dernière version publiée), et le transmet directement à votre shell :

# 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

Le programme d’installation récupère le binaire de la passerelle sur releases.chatcode.dev et vérifie sa somme de contrôle SHA-256 avant de l’installer. Vous pouvez fixer une version (--version vX.Y.Z) au lieu de suivre latest, ou compiler le binaire vous-même et l’installer avec --binary-source /path/to/chatcode-gateway.

Sudo sans mot de passe (et comment il reste sous contrôle)

Quand un agent que vous pilotez doit effectuer une action d’administration (installer un paquet, redémarrer un service), il ne peut pas s’arrêter pour vous demander un mot de passe via Telegram. La passerelle est donc configurée pour l’administration sans surveillance :

  • Linux : l’utilisateur vibe dispose de sudo en NOPASSWD, mais chaque commande est enregistrée (use_pty) dans un journal en ajout seul appartenant à root, /var/log/chatcode/sudo-vibe.log, que vibe peut lire mais pas modifier, avec une rotation sur 14 jours. Vous pouvez vérifier précisément ce qui a été exécuté.
  • macOS : le sudo sans mot de passe est facultatif : il n’est mis en place que si vous l’acceptez pendant l’installation. Si vous le refusez, la passerelle fonctionne quand même ; votre mot de passe vous sera simplement demandé (ou les tâches d’administration ne s’exécuteront pas), comme sur n’importe quel Mac.

C’est un compromis délibéré pour que tout « fonctionne pendant votre absence », rendu vérifiable plutôt que dissimulé.

Demandes d’autorisation de macOS : pas de panique

Si vous faites tourner la passerelle sur votre Mac, vous verrez probablement des demandes de macOS comme celle-ci :

« chatcode-gateway » souhaite accéder aux fichiers de votre dossier Documents.

…ou des demandes concernant votre Bureau, vos Téléchargements, les volumes amovibles, l’Accessibilité ou l’Enregistrement de l’écran. Cela peut sembler inquiétant, comme si la passerelle voulait fouiner. Ce n’est pas le cas.

Voici ce qui se passe réellement : sur macOS, la passerelle s’exécute sous votre compte, et elle exécute l’agent que vous avez demandé. Lorsque cet agent lit un fichier dans un dossier protégé, ou qu’un outil qu’il lance doit automatiser l’interface ou capturer l’écran, le système de confidentialité de macOS (TCC) intervient et demande votre consentement, en attribuant la demande au processus qui a lancé le travail, c’est-à-dire chatcode-gateway. Le nom affiché dans la boîte de dialogue est donc celui de la passerelle, mais l’intention est celle de votre agent, qui accomplit la tâche que vous lui avez confiée.

Ce qu’il faut faire :

  • Autorisez ce à quoi vous vous attendez. Si vous avez demandé à l’agent de travailler sur des fichiers de ~/Documents, autoriser l’accès à Documents est exactement ce qu’il faut.
  • Refusez le reste. Vous gardez toujours la main ; refuser signifie simplement que l’agent ne peut pas toucher à cette ressource.
  • Gérez ces accès à tout moment dans Réglages Système → Confidentialité et sécurité (Fichiers et dossiers, Accessibilité, Enregistrement de l’écran).

Sur Linux, il n’y a pas de boîte de dialogue équivalente : l’utilisateur vibe dispose simplement de ses propres permissions Unix, isolées de votre compte.

Comment elle communique

Browser / Telegram  ⇄  Chatcode control plane  ⇄  your gateway  ⇄  agent session
      (you)                  (TLS relay)            (your machine)   (Claude/Codex/…)
  • La passerelle établit une connexion sortante vers le plan de contrôle via un WebSocket TLS (wss://…). Elle n’ouvre jamais de port entrant sur votre machine.
  • Le navigateur et Telegram se connectent au plan de contrôle, qui relaie le trafic vers votre passerelle.
  • Votre authentification repose sur un cookie de session ; la passerelle s’authentifie avec un token propre à chaque passerelle. Le plan de contrôle ne stocke pas vos clés SSH privées.

Pas de chiffrement de bout en bout, et pourquoi

Il n’y a pas de chiffrement de bout en bout entre votre navigateur et la passerelle, et c’est un choix de conception délibéré, pas un oubli. Chaque tronçon est chiffré en TLS, mais le plan de contrôle assure la terminaison de ces connexions afin de pouvoir traiter le contenu des sessions pour faire fonctionner l’expérience Telegram : mise en forme de la sortie de l’agent pour la conversation, rendu des aperçus de fichiers, transcription des messages vocaux et choix du moment où vous notifier. Ce traitement nécessite des données lisibles : le plan de contrôle occupe donc une position de relais de confiance et peut lire le trafic du terminal.

Nous préférons le dire clairement plutôt que de laisser entendre une garantie que nous n’offrons pas. Votre code, vos identifiants et vos sessions d’agent restent uniquement sur votre machine. Si vous voulez aussi garder le relais sous votre contrôle, vous pouvez auto-héberger le plan de contrôle dans votre propre compte Cloudflare.

Ce que la passerelle affiche dans Telegram

Telegram assure la continuité, et c’est la passerelle qui l’alimente. Lorsque vous ouvrez un aperçu de fichier depuis une conversation, la passerelle lit ce fichier et le renvoie via le relais. Les limites sont volontairement strictes :

  • Lecture seule. Les aperçus n’écrivent jamais rien. Seuls le travail des sessions et les envois de fichiers écrivent, et uniquement dans ~/workspace.
  • Périmètre limité. Les aperçus ne s’ouvrent que sous ~/workspace et dans les chemins non cachés du dossier personnel de l’utilisateur de la passerelle. Les répertoires cachés comme ~/.ssh, ~/.claude et ~/.codex sont inaccessibles, sauf s’ils se trouvent dans ~/workspace ; la vérification porte sur le chemin réel, une fois les liens symboliques résolus, et ne peut donc pas être contournée avec un lien symbolique.
  • Liens de courte durée. Le téléchargement d’un aperçu utilise une URL de type bearer, sans cookie, qui expire au bout d’environ cinq minutes.

Une réserve mérite d’être énoncée clairement : la racine de lecture des aperçus inclut les fichiers non cachés situés n’importe où dans le dossier personnel de l’utilisateur de la passerelle. Gardez donc vos secrets hors de ce dossier personnel (sur Linux, il s’agit de /home/vibe), et pas seulement hors des dotfiles.

Confiance et confidentialité : récapitulatif

  • Votre machine, votre abonnement. Les agents tournent sur du matériel qui vous appartient, avec votre propre connexion Claude/ChatGPT. Chatcode est le relais, pas un cloud qui copie votre dépôt ailleurs.
  • Aucun port entrant. Uniquement un WebSocket sortant. L’accès SSH pour une session de débogage est distinct et à activer vous-même (vous ajoutez une clé ; aucune n’est configurée par défaut).
  • Limite de l’espace de travail. Le travail des sessions et les envois de fichiers sont cantonnés à ~/workspace ; les aperçus Telegram sont en lecture seule et à périmètre limité (détails ci-dessus).
  • Administration vérifiable. Le sudo sans mot de passe sur Linux est consigné dans un fichier en ajout seul appartenant à root.
  • Secrets au repos. Le fichier d’environnement qui contient le token de votre passerelle est en mode 600.

Vérifier ce qui s’exécute

Vous n’êtes pas obligé de nous croire sur parole :

  1. Lisez le programme d’installation. C’est un simple script shell que vous lancez vous-même : examinez-le avant qu’il ne touche à la machine.
  2. Vérifiez la somme de contrôle. Chaque version publiée est livrée avec un fichier .sha256 ; le programme d’installation effectue la vérification, et vous pouvez la refaire vous-même.
  3. Fixez une version avec --version vX.Y.Z au lieu de latest.
  4. Compilez depuis les sources et installez avec --binary-source.
  5. Auto-hébergez le plan de contrôle dans votre propre compte Cloudflare pour garder la maîtrise complète du relais.

Nous documentons le protocole de la passerelle et ouvrons progressivement une plus grande partie du code source, afin que le relais et le comportement sur la machine puissent être vérifiés de manière indépendante : c’est la transparence qui permet de gagner la confiance.

Mise à jour et désinstallation

  • Mise à jour : une tâche de maintenance quotidienne met automatiquement à jour la passerelle et les CLI des agents. Pour mettre à jour tout de suite, relancez le programme d’installation avec une --version plus récente.
  • Statut / journaux : systemctl status chatcode-gateway et journalctl -u chatcode-gateway sur Linux ; ~/Library/Logs/chatcode-gateway.log sur macOS.
  • Désinstallation : lancez le script de nettoyage. Il est destructif par défaut : lisez-le d’abord.
# 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

Options utiles : --keep-user (Linux : conserve l’utilisateur vibe et son dossier personnel), --keep-workspace, --remove-workspace (macOS : supprime aussi ~/workspace) et --kill-tmux. Sur macOS, ~/workspace est conservé, sauf si vous passez --remove-workspace.


Vous débutez ? Commencez par Comment utiliser Claude Code dans Telegram avec Chatcode pour une vue d’ensemble de la mise en place.

Questions fréquentes

Ai-je besoin de mon propre serveur pour faire tourner la passerelle ?

Non. En mode facile, Chatcode se connecte à DigitalOcean et provisionne un droplet Linux qui fait tourner la passerelle pour vous. Si vous utilisez votre propre machine, la même passerelle s’installe sur un serveur Linux ou un Mac que vous possédez déjà.

Pourquoi macOS indique-t-il que chatcode-gateway veut accéder à mes dossiers Documents ou Téléchargements, ou à mon écran ?

Sur macOS, la passerelle s’exécute sous votre propre utilisateur : l’agent de codage que vous pilotez (Claude Code, Codex, etc.) a donc les mêmes accès aux fichiers que vous. Lorsque cet agent lit un dossier protégé ou utilise une fonction protégée, macOS affiche sa demande de confidentialité standard et l’attribue au processus qui a lancé l’agent, c’est-à-dire la passerelle. C’est votre agent qui fait ce que vous lui avez demandé, et macOS vous le signale par son mécanisme de consentement habituel. Autorisez ce à quoi vous vous attendez ; refusez le reste.

La passerelle ouvre-t-elle des ports sur ma machine ?

Aucun port entrant. La passerelle établit une connexion WebSocket TLS sortante vers le plan de contrôle de Chatcode, et le plan de contrôle relaie le trafic de votre navigateur et de Telegram. (L’accès SSH pour une session de débogage est distinct et doit être activé explicitement.)

Chatcode peut-il voir le trafic de mon terminal ?

En transit, oui. Le trafic est chiffré en TLS sur chaque tronçon, mais il n’y a pas de chiffrement de bout en bout entre votre navigateur et la passerelle, et c’est voulu. Le plan de contrôle traite le contenu des sessions pour faire fonctionner l’expérience Telegram (mise en forme de la sortie de l’agent, aperçus de fichiers, transcription vocale, notifications) : il occupe donc une position de relais de confiance et peut lire les données du terminal. Votre code, vos clés et vos sessions d’agent restent uniquement sur votre machine ; pour contrôler aussi le relais, auto-hébergez-le.

Pourquoi la passerelle utilise-t-elle sudo sans mot de passe sur Linux ?

Pour qu’un agent que vous pilotez puisse effectuer des tâches d’administration (installer un paquet, redémarrer un service) sans rester bloqué sur une demande de mot de passe à laquelle vous ne pouvez pas répondre à distance. Sur Linux, la passerelle s’exécute sous un utilisateur dédié vibe, et chaque commande sudo est consignée dans un journal en ajout seul, appartenant à root, que vous pouvez consulter.