El gateway de Chatcode
Qué es el gateway de Chatcode, dónde se ejecuta (Linux o macOS), cómo habla con Chatcode, qué confianza implica y por qué macOS muestra avisos de permisos.
El gateway es el pequeño programa que hace funcionar Chatcode en una máquina de tu propiedad. Ejecuta tus agentes de programación (Claude Code, Codex, Gemini, OpenCode) y los conecta con el navegador en app.chatcode.dev y con Telegram, sin exponer nada a conexiones entrantes en tu máquina.
Esta página explica en términos claros qué es, dónde se instala, cómo se comunica con Chatcode y qué contrapartidas de confianza tiene, incluido por qué macOS a veces muestra avisos de permisos que parecen alarmantes (en resumen: es tu agente haciendo lo que le pediste).
Qué es el gateway
- Un único binario,
chatcode-gateway(compilado para cada plataforma: Linux/macOS × Intel/ARM), instalado como servicio en segundo plano. - Mantiene una conexión saliente con el plano de control de Chatcode y ejecuta tus sesiones de agente en espacios de trabajo de
tmuxdentro de~/workspace. - Es la pieza «Tu servidor + gateway» de la arquitectura de Chatcode: navegador ⇄ Chatcode ⇄ tu gateway ⇄ sesión del agente.
- El binario de cada versión se descarga por HTTPS y se verifica con su suma de comprobación (SHA-256) antes de instalarlo.
Dónde se ejecuta: Linux o macOS
El gateway usa dos modelos distintos según el sistema operativo; esta es la mayor diferencia en la práctica.
Linux: un usuario dedicado vibe (aislado)
Es el modelo de los droplets de DigitalOcean del modo fácil y de los servidores Linux propios. El instalador se ejecuta como root y:
- Crea un usuario dedicado
vibe(los agentes se ejecutan comovibe, no con tu cuenta de inicio de sesión) con su espacio de trabajo en/home/vibe/workspace. - Instala un servicio de systemd (
chatcode-gateway.service) que se ejecuta comovibe. - Instala herramientas básicas, entre ellas
tmux,git,ripgrepybubblewrap(para aislar las sesiones de los agentes en un sandbox). - Preinstala Claude Code y Codex y activa un temporizador de mantenimiento diario que actualiza las CLI de los agentes y el propio gateway.
Como los agentes se ejecutan con su propio usuario, quedan aislados de tu cuenta personal y de tus archivos en esa máquina.
macOS: tu propio usuario
Es el modelo que se usa cuando conectas tu propio Mac. El instalador se ejecuta con tu usuario normal (nunca con sudo) y:
- Instala el binario en
~/.local/bin/chatcode-gatewayy un agente de launchd (dev.chatcode.gateway) que arranca al iniciar sesión y se mantiene en ejecución (en los Mac de escritorio,caffeinateevita que el equipo entre en reposo). - Requiere Homebrew, además de
tmux,gitycurl.
Aquí el agente se ejecuta como tú, así que tiene el mismo acceso a archivos que tú. Es cómodo, y es la razón por la que macOS muestra los avisos de permisos que se describen más abajo.
Dónde está cada cosa
| Linux (gestionado) | macOS (tu usuario) | |
|---|---|---|
| Binario | /usr/local/bin/chatcode-gateway |
~/.local/bin/chatcode-gateway |
| Servicio | systemd chatcode-gateway.service |
launchd dev.chatcode.gateway |
| Configuración/entorno | /etc/chatcode/gateway.env (modo 600) |
~/.config/chatcode/gateway.env (modo 600) |
| Se ejecuta como | usuario dedicado vibe |
tu usuario de inicio de sesión |
| Espacio de trabajo | /home/vibe/workspace |
~/workspace |
| Registros | journalctl -u chatcode-gateway |
~/Library/Logs/chatcode-gateway.log |
Instalación
En la app, añade un servidor y Chatcode te dará un comando listo para ejecutar, con el ID de tu gateway, el token de autenticación y la URL del plano de control ya rellenados. El comando descarga el instalador oficial, https://chatcode.dev/install.sh (que redirige a la última versión), y lo pasa directamente a tu 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
El instalador descarga el binario del gateway de releases.chatcode.dev y verifica su suma de comprobación SHA-256 antes de instalarlo. Puedes fijar una versión (--version vX.Y.Z) en lugar de seguir latest, o compilar el binario tú mismo e instalarlo con --binary-source /path/to/chatcode-gateway.
Sudo sin contraseña (y cómo se mantiene bajo control)
Cuando un agente que estás manejando necesita hacer una tarea de administración (instalar un paquete, reiniciar un servicio), no puede pararse a pedirte una contraseña por Telegram. Por eso el gateway está preparado para la administración desatendida:
- Linux: el usuario
vibetiene sudo conNOPASSWD, pero cada comando queda registrado (use_pty) en un registro propiedad de root al que solo se pueden añadir entradas, en/var/log/chatcode/sudo-vibe.log, quevibepuede leer pero no modificar y que se rota conservando 14 días. Puedes auditar exactamente qué se ha ejecutado. - macOS: el sudo sin contraseña es opcional y solo se configura si lo aceptas durante la instalación. Si lo rechazas, el gateway sigue funcionando; simplemente se te pedirá la contraseña (o las tareas de administración no se ejecutarán), como en cualquier Mac normal.
Es una contrapartida deliberada para que todo «funcione mientras no estás», y se ha hecho auditable en lugar de ocultarla.
Avisos de permisos en macOS: no te alarmes
Si ejecutas el gateway en tu Mac, es probable que veas avisos de macOS como este:
«chatcode-gateway» quiere acceder a los archivos de tu carpeta Documentos.
…o avisos sobre tus carpetas Escritorio y Descargas, los volúmenes extraíbles, Accesibilidad o Grabación de pantalla. Puede parecer alarmante, como si el gateway quisiera husmear. No es así.
Esto es lo que ocurre en realidad: en macOS el gateway se ejecuta como tú y ejecuta el agente que tú le pediste. Cuando ese agente lee un archivo de una carpeta protegida, o cuando una herramienta que ejecuta necesita automatizar la interfaz o capturar la pantalla, el sistema de privacidad de macOS (TCC) interviene y pide consentimiento, y atribuye la solicitud al proceso que inició el trabajo, que es chatcode-gateway. Así que en el cuadro de diálogo aparece el nombre del gateway, pero la intención es la de tu agente haciendo la tarea que le encargaste.
Qué hacer:
- Permite lo que esperas. Si le pediste al agente que trabajara con archivos de
~/Documents, permitir el acceso a Documentos es exactamente lo correcto. - Deniega lo que no. Siempre tienes el control; denegar solo significa que el agente no podrá tocar ese recurso.
- Gestiónalo cuando quieras en Ajustes del Sistema → Privacidad y seguridad (con macOS en inglés, System Settings → Privacy & Security), en los apartados Archivos y carpetas, Accesibilidad y Grabación de pantalla.
En Linux no hay un cuadro de diálogo equivalente: el usuario vibe simplemente tiene sus propios permisos de Unix, aislados de tu cuenta.
Cómo se comunica
Browser / Telegram ⇄ Chatcode control plane ⇄ your gateway ⇄ agent session
(you) (TLS relay) (your machine) (Claude/Codex/…)
- El gateway establece una conexión saliente con el plano de control mediante un WebSocket TLS (
wss://…). Nunca abre un puerto de entrada en tu máquina. - El navegador y Telegram se conectan al plano de control, que retransmite el tráfico a tu gateway.
- Tu autenticación usa una cookie de sesión; el gateway se autentica con un token propio de cada gateway. El plano de control no almacena tus claves SSH privadas.
Sin cifrado de extremo a extremo, y por qué
No hay cifrado de extremo a extremo entre tu navegador y el gateway, y es una decisión de diseño deliberada, no un descuido. Cada salto va cifrado con TLS, pero el plano de control termina esas conexiones para poder procesar el contenido de la sesión que hace funcionar la experiencia en Telegram: dar formato a la salida del agente para el chat, generar vistas previas de archivos, transcribir notas de voz y decidir cuándo avisarte. Ese procesamiento necesita cargas útiles legibles, así que el plano de control actúa como intermediario de confianza y puede leer el tráfico del terminal.
Preferimos decirlo claramente antes que dar a entender una garantía que no ofrecemos. Tu código, tus credenciales y tus sesiones de agente siguen estando solo en tu máquina. Si también quieres tener el intermediario bajo tu control, puedes alojar tú mismo el plano de control en tu propia cuenta de Cloudflare.
Qué muestra el gateway en Telegram
Telegram es la capa de continuidad, y el gateway es quien la alimenta. Cuando abres una vista previa de un archivo desde un chat, el gateway lee ese archivo y lo devuelve a través del intermediario. Los límites son deliberadamente estrictos:
- Solo lectura. Las vistas previas nunca escriben. Solo escriben el trabajo de las sesiones y las subidas, y se limitan a
~/workspace. - Acotadas. Las vistas previas se resuelven dentro de
~/workspacey de las rutas no ocultas del directorio personal del usuario del gateway. Los directorios ocultos como~/.ssh,~/.claudey~/.codexquedan fuera de su alcance salvo que estén dentro de~/workspace, y la comprobación se hace sobre la ruta real, con los enlaces simbólicos ya resueltos, así que no se puede engañar con un enlace simbólico. - Enlaces de corta duración. La descarga de una vista previa usa una URL bearer (al portador), sin cookies, que caduca en unos cinco minutos.
Una salvedad que conviene dejar clara: la raíz de lectura de las vistas previas incluye los archivos no ocultos de cualquier parte del directorio personal del usuario del gateway, así que mantén los secretos fuera de ese directorio personal (en Linux es /home/vibe), no solo fuera de los dotfiles.
Resumen de confianza y privacidad
- Tu máquina, tu suscripción. Los agentes se ejecutan en hardware de tu propiedad con tu propio inicio de sesión de Claude/ChatGPT. Chatcode es el intermediario, no una nube que copia tu repositorio a otro sitio.
- Sin puertos de entrada. Solo un WebSocket saliente. El acceso SSH para una sesión de depuración es aparte y solo se activa si tú quieres (tú añades una clave; por defecto no hay ninguna).
- Límite del espacio de trabajo. El trabajo de las sesiones y las subidas se limitan a
~/workspace; las vistas previas en Telegram son de solo lectura y acotadas (detalles más arriba). - Administración auditable. En Linux, el sudo sin contraseña se registra en un archivo propiedad de root al que solo se pueden añadir entradas.
- Secretos en reposo. El archivo de entorno que guarda el token de tu gateway tiene el modo
600.
Verifica lo que se ejecuta
No tienes por qué fiarte de nuestra palabra:
- Lee el instalador. Es un script de shell normal que ejecutas tú mismo: revísalo antes de que toque la máquina.
- Verifica la suma de comprobación. Cada versión incluye un
.sha256; el instalador lo comprueba y tú puedes volver a verificarlo. - Fija una versión con
--version vX.Y.Zen lugar delatest. - Compila desde el código fuente e instala con
--binary-source. - Aloja tú mismo el plano de control en tu propia cuenta de Cloudflare para tener la custodia completa del intermediario.
Estamos documentando el protocolo del gateway y abriendo más código fuente con el tiempo, para que el intermediario y el comportamiento en la máquina puedan verificarse de forma independiente: la transparencia es la forma de ganarse la confianza.
Actualización y desinstalación
- Actualizar: un trabajo de mantenimiento diario actualiza automáticamente el gateway y las CLI de los agentes. Para actualizar ya, vuelve a ejecutar el instalador con una
--versionmás reciente. - Estado y registros:
systemctl status chatcode-gatewayyjournalctl -u chatcode-gatewayen Linux;~/Library/Logs/chatcode-gateway.logen macOS. - Desinstalar: ejecuta el script de limpieza. Es destructivo por defecto: léelo antes.
# 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
Opciones útiles: --keep-user (Linux: conserva el usuario vibe y su directorio personal), --keep-workspace, --remove-workspace (macOS: borra también ~/workspace) y --kill-tmux. En macOS, ~/workspace se conserva a menos que pases --remove-workspace.
¿Todo esto es nuevo para ti? Empieza por Cómo usar Claude Code en Telegram con Chatcode para ver la configuración en su conjunto.
Preguntas frecuentes
¿Necesito mi propio servidor para ejecutar el gateway?
No. En el modo fácil, Chatcode se conecta a DigitalOcean y aprovisiona un droplet Linux que ejecuta el gateway por ti. Si prefieres usar tu propia máquina, se instala el mismo gateway en un servidor Linux o un Mac que ya tengas.
¿Por qué macOS dice que chatcode-gateway quiere acceder a Documentos, a Descargas o a mi pantalla?
En macOS el gateway se ejecuta con tu propio usuario, así que el agente de programación que estás manejando (Claude Code, Codex, etc.) tiene el mismo acceso a archivos que tú. Cuando ese agente lee una carpeta protegida o usa una función protegida, macOS muestra su aviso de privacidad estándar y lo atribuye al proceso que lanzó el agente: el gateway. Es tu agente haciendo lo que le pediste, a través del flujo de consentimiento habitual de macOS. Permite lo que esperas y deniega lo que no.
¿El gateway abre puertos en mi máquina?
No abre ningún puerto de entrada. El gateway establece una conexión WebSocket TLS saliente con el plano de control de Chatcode, y el plano de control retransmite el tráfico de tu navegador y de Telegram. (El SSH para una sesión de depuración es aparte y solo se activa si tú quieres.)
¿Puede Chatcode ver el tráfico de mi terminal?
En tránsito, sí. El tráfico va cifrado con TLS en cada salto, pero no hay cifrado de extremo a extremo entre tu navegador y el gateway, por diseño. El plano de control procesa el contenido de la sesión para hacer posible la experiencia en Telegram (formatear la salida del agente, vistas previas de archivos, transcripción de voz, notificaciones), así que actúa como intermediario de confianza y puede leer las cargas útiles del terminal. Tu código, tus claves y tus sesiones de agente siguen estando solo en tu máquina; si también quieres controlar el intermediario, alójalo tú mismo.
¿Por qué el gateway usa sudo sin contraseña en Linux?
Para que un agente que estás manejando pueda hacer tareas de administración (instalar un paquete, reiniciar un servicio) sin quedarse bloqueado ante una petición de contraseña que no puedes responder en remoto. En Linux se ejecuta con un usuario dedicado vibe, y cada comando sudo queda escrito en un registro propiedad de root al que solo se pueden añadir entradas y que puedes revisar.