Gateway

O gateway do Chatcode

O que é o gateway do Chatcode, onde corre (Linux ou macOS), como comunica com o Chatcode, que confiança exige e porque é que o macOS pede permissões.

O gateway é o pequeno programa que põe o Chatcode a funcionar numa máquina sua. Executa os seus agentes de programação — Claude Code, Codex, Gemini, OpenCode — e liga-os ao browser em app.chatcode.dev e ao Telegram, sem expor na sua máquina nada que aceite ligações de entrada.

Esta página explica o que é, onde fica, como comunica com o Chatcode e, em termos simples, as contrapartidas em matéria de confiança — incluindo o motivo pelo qual o macOS mostra por vezes pedidos de permissão com um aspeto alarmante (em resumo: é o seu agente a fazer o que lhe pediu).

O que é o gateway

  • Um único binário, chatcode-gateway (compilado para cada plataforma: Linux/macOS × Intel/ARM), instalado como serviço em segundo plano.
  • Mantém uma única ligação de saída ao plano de controlo do Chatcode e executa as sessões dos seus agentes em espaços de trabalho tmux dentro de ~/workspace.
  • Corresponde à caixa «O seu servidor + gateway» na arquitetura do Chatcode: browser ⇄ Chatcode ⇄ o seu gateway ⇄ sessão do agente.
  • O binário de cada versão é transferido por HTTPS e a sua soma de verificação (SHA-256) é confirmada antes de ser instalado.

Onde corre: Linux ou macOS

O gateway segue dois modelos diferentes consoante o sistema operativo — e esta é, na prática, a maior diferença.

Linux — um utilizador dedicado vibe (isolado)

Usado pelos droplets da DigitalOcean do modo fácil e pelos seus próprios servidores Linux. O instalador corre como root e:

  • Cria um utilizador dedicado vibe — os agentes correm como vibe, e não com a conta com que inicia sessão na máquina — com o espaço de trabalho em /home/vibe/workspace.
  • Instala um serviço systemd (chatcode-gateway.service) que corre como vibe.
  • Instala ferramentas de base, incluindo tmux, git, ripgrep e bubblewrap (para isolar as sessões dos agentes numa sandbox).
  • Pré-instala o Claude Code e o Codex e ativa um temporizador de manutenção diário que atualiza as CLIs dos agentes e o próprio gateway.

Como os agentes correm com um utilizador próprio, ficam isolados da sua conta pessoal e dos seus ficheiros nessa máquina.

macOS — o seu próprio utilizador

Usado quando liga o seu próprio Mac. O instalador corre com o seu utilizador normal (nunca com sudo) e:

  • Instala o binário em ~/.local/bin/chatcode-gateway e um agente launchd (dev.chatcode.gateway) que arranca quando inicia sessão e se mantém em execução (nos Macs de secretária, o computador é mantido acordado com caffeinate).
  • Requer o Homebrew, além de tmux, git e curl.

Aqui, o agente corre com o seu utilizador, pelo que tem exatamente o mesmo acesso a ficheiros que a sua conta. É cómodo — e é o motivo pelo qual o macOS mostra os pedidos de permissão descritos mais abaixo.

Onde fica cada coisa

Linux (gerido) macOS (o seu utilizador)
Binário /usr/local/bin/chatcode-gateway ~/.local/bin/chatcode-gateway
Serviço systemd chatcode-gateway.service launchd dev.chatcode.gateway
Configuração/ambiente /etc/chatcode/gateway.env (modo 600) ~/.config/chatcode/gateway.env (modo 600)
Corre como utilizador dedicado vibe o utilizador com que inicia sessão
Espaço de trabalho /home/vibe/workspace ~/workspace
Registos journalctl -u chatcode-gateway ~/Library/Logs/chatcode-gateway.log

Instalação

Na aplicação, adicione um servidor e o Chatcode dá-lhe um comando pronto a executar, já preenchido com o ID do gateway, o token de autenticação e o URL do plano de controlo. O comando passa à sua shell o instalador oficial em https://chatcode.dev/install.sh (que redireciona para a versão mais recente):

# 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

O instalador obtém o binário do gateway em releases.chatcode.dev e confirma a respetiva soma de verificação SHA-256 antes de o instalar. Pode fixar uma versão (--version vX.Y.Z) em vez de acompanhar a latest, ou compilar o binário por conta própria e instalá-lo com --binary-source /path/to/chatcode-gateway.

Sudo sem palavra-passe (e como se mantém transparente)

Quando um agente que está a utilizar precisa de executar uma ação de administração — instalar um pacote, reiniciar um serviço —, não pode parar e pedir-lhe uma palavra-passe através do Telegram. Por isso, o gateway está preparado para tarefas de administração sem supervisão:

  • Linux: o utilizador vibe tem sudo NOPASSWD, mas cada comando fica gravado (use_pty) num registo pertencente ao root e só de acréscimo (append-only), em /var/log/chatcode/sudo-vibe.log, que o vibe pode ler mas não alterar, com rotação ao longo de 14 dias. Pode auditar exatamente o que foi executado.
  • macOS: o sudo sem palavra-passe é opcional e só é proposto se o aceitar durante a instalação. Se o recusar, o gateway continua a funcionar; apenas lhe será pedida a palavra-passe (ou as tarefas de administração não serão executadas), como em qualquer Mac normal.

Trata-se de uma contrapartida deliberada para que tudo «funcione enquanto está ausente», tornada auditável em vez de escondida.

Pedidos de permissão do macOS: não entre em pânico

Se executar o gateway no seu Mac, é provável que veja pedidos do macOS como este:

“chatcode-gateway” pretende aceder a ficheiros na pasta Documentos.

…ou pedidos relativos às pastas Secretária e Descargas, a volumes amovíveis, à Acessibilidade ou à Gravação do ecrã. Isto pode parecer alarmante — como se o gateway quisesse bisbilhotar. Não é o caso.

Eis o que realmente acontece: no macOS, o gateway corre com o seu utilizador e executa o agente a seu pedido. Quando esse agente lê um ficheiro numa pasta protegida, ou quando uma ferramenta que ele executa precisa de automatizar a interface ou de capturar o ecrã, o sistema de privacidade do macOS (TCC) intervém e pede consentimento — e atribui o pedido ao processo que lançou o trabalho, que é o chatcode-gateway. Assim, o nome que aparece na caixa de diálogo é o do gateway, mas a intenção é a do seu agente, a realizar a tarefa que lhe deu.

O que fazer:

  • Permita o que espera. Se pediu ao agente que trabalhasse com ficheiros em ~/Documents, permitir o acesso a Documentos é exatamente o correto.
  • Recuse o que não espera. O controlo é sempre seu; recusar significa apenas que o agente não pode tocar nesse recurso.
  • Pode gerir isto a qualquer momento em Definições do Sistema → Privacidade e segurança (System Settings → Privacy & Security), nas secções Ficheiros e pastas, Acessibilidade e Gravação do ecrã.

Em Linux não existe uma caixa de diálogo equivalente — o utilizador vibe tem simplesmente as suas próprias permissões Unix, isoladas da sua conta.

Como comunica

Browser / Telegram  ⇄  Chatcode control plane  ⇄  your gateway  ⇄  agent session
      (you)                  (TLS relay)            (your machine)   (Claude/Codex/…)
  • O gateway liga para fora, ao plano de controlo, através de um WebSocket TLS (wss://…). Nunca abre uma porta de entrada na sua máquina.
  • O browser e o Telegram ligam-se ao plano de controlo, que retransmite o tráfego para o seu gateway.
  • A sua autenticação faz-se com um cookie de sessão; o gateway autentica-se com um token próprio de cada gateway. O plano de controlo não guarda as suas chaves SSH privadas.

Sem encriptação ponta a ponta, e porquê

Não existe encriptação ponta a ponta entre o seu browser e o gateway, e trata-se de uma opção de design deliberada, não de um descuido. Cada troço é encriptado com TLS, mas o plano de controlo termina essas ligações para poder processar o conteúdo da sessão que faz a experiência no Telegram funcionar — formatar a saída do agente para a conversa, gerar pré-visualizações de ficheiros, transcrever mensagens de voz e decidir quando o notificar. Esse processamento precisa de conteúdo legível, por isso o plano de controlo ocupa uma posição de intermediário de confiança e consegue ler o tráfego do terminal.

Preferimos dizê-lo claramente a sugerir uma garantia que não oferecemos. O seu código, as suas credenciais e as sessões dos agentes continuam a residir apenas na sua máquina. Se quiser ter também o intermediário sob o seu controlo, pode alojar o próprio plano de controlo na sua conta da Cloudflare.

O que o gateway mostra no Telegram

O Telegram é a camada de continuidade, e é o gateway que a serve. Quando abre uma pré-visualização de ficheiro a partir de uma conversa, o gateway lê esse ficheiro e devolve-o através do intermediário. Os limites são deliberadamente apertados:

  • Só de leitura. As pré-visualizações nunca escrevem. Só o trabalho das sessões e os carregamentos escrevem, e estão confinados a ~/workspace.
  • Âmbito limitado. As pré-visualizações só abrem caminhos dentro de ~/workspace e caminhos não ocultos no diretório pessoal do utilizador do gateway. Diretórios ocultos como ~/.ssh, ~/.claude e ~/.codex estão vedados, a menos que se encontrem dentro de ~/workspace — e a verificação é feita sobre o caminho real, depois de resolvidas as ligações simbólicas, pelo que não pode ser contornada com um symlink.
  • Links de curta duração. A transferência de uma pré-visualização usa um URL com token de portador (bearer), sem cookies, que expira ao fim de cerca de cinco minutos.

Uma ressalva que vale a pena deixar clara: a raiz de leitura das pré-visualizações inclui ficheiros não ocultos em qualquer ponto do diretório pessoal do utilizador do gateway — por isso, mantenha os segredos fora desse diretório pessoal (em Linux, é /home/vibe), e não apenas fora dos ficheiros ocultos (dotfiles).

Resumo de confiança e privacidade

  • A sua máquina, a sua subscrição. Os agentes correm em hardware seu, com a sua própria conta do Claude/ChatGPT. O Chatcode é o intermediário, não uma nuvem que copia o seu repositório para outro lado.
  • Sem portas de entrada. Apenas um WebSocket de saída. O acesso SSH para uma sessão de depuração é à parte e só é ativado se o pedir (a chave é adicionada por si; por omissão, não há nenhuma).
  • Fronteira do espaço de trabalho. O trabalho das sessões e os carregamentos estão limitados a ~/workspace; as pré-visualizações no Telegram são só de leitura e têm âmbito limitado (detalhes acima).
  • Administração auditável. Em Linux, o sudo sem palavra-passe fica registado num ficheiro só de acréscimo, pertencente ao root.
  • Segredos em repouso. O ficheiro de ambiente que contém o token do gateway tem o modo 600.

Verifique o que é executado

Não tem de acreditar apenas na nossa palavra:

  1. Leia o instalador. É um simples script de shell, executado por si — inspecione-o antes de ele tocar na máquina.
  2. Confirme a soma de verificação. Cada versão inclui um ficheiro .sha256; o instalador verifica-o, e pode voltar a verificá-lo por si.
  3. Fixe uma versão com --version vX.Y.Z em vez de latest.
  4. Compile a partir do código-fonte e instale com --binary-source.
  5. Aloje o próprio plano de controlo na sua conta da Cloudflare, para ter a custódia total do intermediário.

Estamos a documentar o protocolo do gateway e a abrir mais partes do código-fonte ao longo do tempo, para que o intermediário e o comportamento na máquina possam ser verificados de forma independente — é com transparência que isto conquista confiança.

Atualizar e desinstalar

  • Atualizar: uma tarefa de manutenção diária atualiza automaticamente o gateway e as CLIs dos agentes. Para atualizar já, volte a executar o instalador com uma --version mais recente.
  • Estado / registos: systemctl status chatcode-gateway e journalctl -u chatcode-gateway em Linux; ~/Library/Logs/chatcode-gateway.log no macOS.
  • Desinstalar: execute o script de limpeza. É destrutivo por omissão — leia-o primeiro.
# 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

Opções úteis: --keep-user (Linux: mantém o utilizador vibe e o respetivo diretório pessoal), --keep-workspace, --remove-workspace (macOS: apaga também ~/workspace) e --kill-tmux. No macOS, ~/workspace é mantido, a menos que passe --remove-workspace.


Se tudo isto é novo para si, comece por Como usar o Claude Code no Telegram com o Chatcode para ter uma visão geral da configuração.

Perguntas frequentes

Preciso de ter o meu próprio servidor para executar o gateway?

Não. No modo fácil, o Chatcode liga-se à DigitalOcean e aprovisiona um droplet Linux que executa o gateway por si. A opção de usar o seu próprio servidor instala o mesmo gateway num servidor Linux ou num Mac que já tenha.

Porque é que o macOS diz que o chatcode-gateway quer aceder às minhas pastas Documentos / Descargas ou ao meu ecrã?

No macOS, o gateway corre com o seu próprio utilizador, pelo que o agente de programação que está a utilizar (Claude Code, Codex, etc.) tem o mesmo acesso a ficheiros que a sua conta. Quando esse agente lê uma pasta protegida ou usa uma capacidade protegida, o macOS mostra o pedido de privacidade habitual e atribui-o ao processo que lançou o agente: o gateway. É o seu agente a fazer o que lhe pediu, apresentado através do fluxo de consentimento normal do macOS. Permita o que espera; recuse o que não espera.

O gateway abre portas na minha máquina?

Não abre portas de entrada. O gateway estabelece uma ligação WebSocket TLS de saída ao plano de controlo do Chatcode, e o plano de controlo retransmite o tráfego do seu browser e do Telegram. (O SSH para uma sessão de depuração é à parte e só é ativado se o pedir.)

O Chatcode consegue ver o tráfego do meu terminal?

Em trânsito, sim. O tráfego é encriptado com TLS em cada troço, mas não há encriptação ponta a ponta entre o seu browser e o gateway, e isso é intencional. O plano de controlo processa o conteúdo das sessões para dar suporte à experiência no Telegram (formatação da saída do agente, pré-visualizações de ficheiros, transcrição de voz, notificações), pelo que ocupa uma posição de intermediário de confiança e consegue ler o conteúdo do terminal. O seu código, as suas chaves e as sessões dos agentes continuam a residir apenas na sua máquina; para controlar também o intermediário, aloje-o por conta própria.

Porque é que o gateway usa sudo sem palavra-passe em Linux?

Para que um agente que está a utilizar possa executar tarefas de administração (instalar um pacote, reiniciar um serviço) sem ficar parado num pedido de palavra-passe a que não consegue responder à distância. Em Linux, o gateway corre com um utilizador dedicado vibe, e cada comando sudo é escrito num registo só de acréscimo, pertencente ao root, que pode consultar.