---
title: "La passerelle Chatcode"
seoTitle: "Passerelle Chatcode : installation, confiance et fonctionnement"
navTitle: "Passerelle"
description: "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."
slug: gateway
lang: fr
date: 2026-06-12
updated: 2026-06-12
author: "Chatcode"
section: "Passerelle"
faq:
  - q: "Ai-je besoin de mon propre serveur pour faire tourner la passerelle ?"
    a: "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à."
  - q: "Pourquoi macOS indique-t-il que chatcode-gateway veut accéder à mes dossiers Documents ou Téléchargements, ou à mon écran ?"
    a: "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."
  - q: "La passerelle ouvre-t-elle des ports sur ma machine ?"
    a: "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.)"
  - q: "Chatcode peut-il voir le trafic de mon terminal ?"
    a: "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."
  - q: "Pourquoi la passerelle utilise-t-elle sudo sans mot de passe sur Linux ?"
    a: "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."
---

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](https://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](/articles/claude-code-telegram-with-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 :

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

```bash
# 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](/articles/claude-code-telegram-with-chatcode)** pour une vue d’ensemble de la mise en place.
