Шлюз

Шлюз Chatcode

Что такое шлюз Chatcode, где он работает (Linux и macOS), как связывается с Chatcode, в чём компромиссы доверия и почему macOS запрашивает разрешения.

Шлюз — это небольшая программа, благодаря которой Chatcode работает на вашей машине. Он запускает ваших агентов для программирования — Claude Code, Codex, Gemini, OpenCode — и подключает их к браузеру на app.chatcode.dev и к Telegram, не открывая на вашей машине ничего для входящих подключений.

Ниже мы простыми словами объясним, что такое шлюз, где он размещается, как связывается с Chatcode и на какие компромиссы доверия при этом приходится идти, — в том числе почему macOS иногда показывает пугающие на вид запросы разрешений (если коротко: это ваш агент делает то, о чём вы попросили).

Что такое шлюз

  • Один бинарный файл, chatcode-gateway (собирается под каждую платформу: Linux/macOS × Intel/ARM), который устанавливается как фоновая служба.
  • Он держит одно исходящее соединение с управляющим слоем Chatcode и запускает сессии агентов в рабочих пространствах tmux внутри ~/workspace.
  • Это блок «Ваш сервер + шлюз» в архитектуре Chatcode: браузер ⇄ Chatcode ⇄ ваш шлюз ⇄ сессия агента.
  • Бинарный файл релиза загружается по HTTPS и перед установкой проходит проверку контрольной суммы (SHA-256).

Где он работает: Linux и macOS

В зависимости от ОС шлюз работает по одной из двух моделей — на практике это самое важное различие.

Linux — отдельный пользователь vibe (изоляция)

Используется на дроплетах DigitalOcean, созданных в простом варианте, и на ваших собственных Linux-серверах. Установщик запускается от root и:

  • создаёт отдельного пользователя vibe — агенты работают от имени vibe, а не вашей учётной записи — с рабочим пространством в /home/vibe/workspace;
  • устанавливает службу systemd (chatcode-gateway.service), которая работает от имени vibe;
  • устанавливает базовые инструменты, в том числе tmux, git, ripgrep и bubblewrap (для запуска сессий агентов в песочнице);
  • заранее устанавливает Claude Code и Codex и включает ежедневный таймер обслуживания, который обновляет CLI агентов и сам шлюз.

Поскольку агенты работают от имени собственного пользователя, на этой машине они изолированы от вашей личной учётной записи и ваших файлов.

macOS — ваш собственный пользователь

Используется, когда вы подключаете собственный Mac. Установщик запускается от имени вашего обычного пользователя (никогда не через sudo) и:

  • устанавливает бинарный файл в ~/.local/bin/chatcode-gateway и агент launchd (dev.chatcode.gateway), который запускается при входе в систему и работает постоянно (на настольных Mac caffeinate не даёт системе уснуть);
  • требует Homebrew, а также tmux, git и curl.

Здесь агент работает от вашего имени, поэтому у него тот же доступ к файлам, что и у вас. Это удобно — и именно поэтому macOS показывает запросы разрешений, о которых речь пойдёт ниже.

Где что находится

Linux (управляемый) macOS (ваш пользователь)
Бинарный файл /usr/local/bin/chatcode-gateway ~/.local/bin/chatcode-gateway
Служба systemd chatcode-gateway.service launchd dev.chatcode.gateway
Конфигурация/env /etc/chatcode/gateway.env (права 600) ~/.config/chatcode/gateway.env (права 600)
Работает от имени отдельного пользователя vibe вашего пользователя
Рабочее пространство /home/vibe/workspace ~/workspace
Логи journalctl -u chatcode-gateway ~/Library/Logs/chatcode-gateway.log

Установка

В приложении добавьте сервер, и Chatcode выдаст готовую команду, в которую уже подставлены идентификатор вашего шлюза, токен аутентификации и URL управляющего слоя. Команда скачивает канонический установщик https://chatcode.dev/install.sh (адрес перенаправляет на последний релиз) и передаёт его в вашу оболочку:

# 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

Установщик загружает бинарный файл шлюза с releases.chatcode.dev и перед установкой проверяет его контрольную сумму SHA-256. Вместо того чтобы отслеживать latest, можно закрепить версию (--version vX.Y.Z) или собрать бинарный файл самостоятельно и установить его с --binary-source /path/to/chatcode-gateway.

Доступ к sudo без пароля (и как он остаётся под контролем)

Когда агенту, которым вы управляете, нужно выполнить административное действие — установить пакет, перезапустить службу, — он не может остановиться и спросить у вас пароль через Telegram. Поэтому шлюз настроен на администрирование без участия человека:

  • Linux: пользователь vibe получает sudo с NOPASSWD, но каждая команда записывается (use_pty) в принадлежащий root журнал только для дозаписи /var/log/chatcode/sudo-vibe.log. vibe может его читать, но не может изменить; журнал ротируется и хранится 14 дней. Можно в точности проверить, что выполнялось.
  • macOS: sudo без пароля необязателен и предлагается, только если вы сами на него согласитесь во время установки. Если откажетесь, шлюз всё равно будет работать — просто, как на любом обычном Mac, у вас будут спрашивать пароль (или административные задачи не выполнятся).

Это сознательный компромисс ради того, чтобы всё «работало, пока вас нет», — и сделан он проверяемым, а не скрытым.

Запросы разрешений в macOS — без паники

Если вы запускаете шлюз на своём Mac, скорее всего, увидите запросы macOS вроде такого:

«chatcode-gateway» запрашивает доступ к файлам в папке «Документы».

…или запросы, связанные с папками «Рабочий стол» и «Загрузки», съёмными носителями, Универсальным доступом или Записью экрана. Выглядит это тревожно — будто шлюз хочет за вами подглядывать. Это не так.

Вот что происходит на самом деле: на macOS шлюз работает от вашего имени и запускает агента по вашему запросу. Когда агент читает файл в защищённой папке или запущенному им инструменту нужно управлять интерфейсом либо захватывать изображение экрана, вмешивается система конфиденциальности macOS (TCC): она запрашивает согласие и приписывает запрос процессу, который запустил работу, то есть chatcode-gateway. Поэтому в диалоге стоит имя шлюза, но на деле это ваш агент выполняет поставленную вами задачу.

Что делать:

  • Разрешайте то, чего ожидаете. Если вы попросили агента поработать с файлами в ~/Documents, разрешить доступ к «Документам» — как раз правильное решение.
  • Отклоняйте то, чего не ожидаете. Решение всегда за вами: отказ лишь означает, что агент не сможет обратиться к этому ресурсу.
  • Меняйте настройки в любой момент в разделе Системные настройки → Конфиденциальность и безопасность (System Settings → Privacy & Security): «Файлы и папки», «Универсальный доступ», «Запись экрана».

На Linux подобных диалогов нет — у пользователя vibe просто свои права Unix, изолированные от вашей учётной записи.

Как устроена связь

Browser / Telegram  ⇄  Chatcode control plane  ⇄  your gateway  ⇄  agent session
      (you)                  (TLS relay)            (your machine)   (Claude/Codex/…)
  • Шлюз сам устанавливает исходящее соединение с управляющим слоем по TLS WebSocket (wss://…). Входящий порт на вашей машине он никогда не открывает.
  • Браузер и Telegram подключаются к управляющему слою, который ретранслирует трафик на ваш шлюз.
  • Вы аутентифицируетесь с помощью сессионного cookie, а шлюз — с помощью отдельного токена, выданного именно ему. Управляющий слой не хранит ваши приватные SSH-ключи.

Сквозного шифрования нет — и вот почему

Сквозного шифрования между вашим браузером и шлюзом нет, и это сознательное архитектурное решение, а не недосмотр. Каждый участок шифруется TLS, но эти соединения завершаются на управляющем слое, чтобы он мог обрабатывать содержимое сессий, на котором держится работа в Telegram: форматировать вывод агента для чата, показывать превью файлов, расшифровывать голосовые сообщения и решать, когда отправить вам уведомление. Для такой обработки данные должны быть читаемыми, поэтому управляющий слой выступает доверенным ретранслятором и может читать терминальный трафик.

Мы предпочитаем сказать об этом прямо, а не намекать на гарантии, которых не даём. Ваш код, учётные данные и сессии агентов по-прежнему находятся только на вашей машине. Если вы хотите контролировать и ретранслятор, можно развернуть управляющий слой у себя — в собственном аккаунте Cloudflare.

Что шлюз показывает в Telegram

Telegram отвечает за непрерывность работы, а содержимое для него отдаёт шлюз. Когда вы открываете превью файла из чата, шлюз читает этот файл и возвращает его через ретранслятор. Границы намеренно узкие:

  • Только чтение. Превью никогда ничего не записывают. Запись возможна только при работе в сессиях и загрузке файлов, и она ограничена ~/workspace.
  • Ограниченная область. Превью открываются только для путей внутри ~/workspace и нескрытых путей в домашней директории пользователя шлюза. Скрытые хранилища вроде ~/.ssh, ~/.claude и ~/.codex недоступны, если только они не лежат внутри ~/workspace, — причём проверка выполняется по реальному пути после разрешения символических ссылок, так что обойти её с помощью симлинка не получится.
  • Короткоживущие ссылки. Для скачивания превью используется bearer-ссылка без cookie, которая истекает примерно через пять минут.

Одну оговорку стоит сделать прямо: корень для чтения превью включает нескрытые файлы в любом месте домашней директории пользователя шлюза, поэтому не держите секреты в этой домашней директории вообще (на Linux это /home/vibe), а не только в dot-файлах.

Доверие и конфиденциальность: коротко

  • Ваша машина, ваша подписка. Агенты работают на вашем оборудовании с вашим собственным аккаунтом Claude/ChatGPT. Chatcode — ретранслятор, а не облако, которое копирует ваш репозиторий куда-то ещё.
  • Никаких входящих портов. Только исходящий WebSocket. SSH-доступ для отладки отдельный и включается только по вашему желанию (вы сами добавляете ключ; по умолчанию ключей нет).
  • Граница рабочего пространства. Работа в сессиях и загрузки ограничены ~/workspace; превью в Telegram доступны только для чтения и ограничены по области (подробности выше).
  • Проверяемое администрирование. На Linux действия через sudo без пароля записываются в принадлежащий root файл только для дозаписи.
  • Секреты на диске. У env-файла с токеном вашего шлюза права 600.

Проверьте, что запускается

Не обязательно верить нам на слово:

  1. Прочитайте установщик. Это обычный shell-скрипт, который вы запускаете сами, — изучите его, прежде чем он что-то сделает на машине.
  2. Проверьте контрольную сумму. К каждому релизу прилагается .sha256; установщик проверяет её, и вы можете перепроверить сами.
  3. Закрепите версию с помощью --version vX.Y.Z вместо latest.
  4. Соберите из исходников и установите с --binary-source.
  5. Разверните управляющий слой у себя в собственном аккаунте Cloudflare, чтобы ретранслятор был полностью под вашим контролем.

Мы документируем протокол шлюза и постепенно открываем всё больше исходного кода, чтобы работу ретранслятора и поведение шлюза на машине можно было проверить независимо: доверие мы хотим заслужить прозрачностью.

Обновление и удаление

  • Обновление: ежедневная задача обслуживания автоматически обновляет шлюз и CLI агентов. Чтобы обновиться прямо сейчас, повторно запустите установщик с более новой --version.
  • Статус и логи: systemctl status chatcode-gateway и journalctl -u chatcode-gateway на Linux; ~/Library/Logs/chatcode-gateway.log на macOS.
  • Удаление: запустите скрипт очистки. По умолчанию его действия необратимы — сначала прочитайте его.
# 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

Полезные флаги: --keep-user (Linux: сохранить пользователя vibe и его домашнюю директорию), --keep-workspace, --remove-workspace (macOS: заодно удалить ~/workspace) и --kill-tmux. На macOS ~/workspace сохраняется, если не передать --remove-workspace.


Всё это в новинку? Начните с руководства Как пользоваться Claude Code в Telegram через Chatcode — в нём описана общая схема настройки.

Часто задаваемые вопросы

Нужен ли собственный сервер, чтобы запустить шлюз?

Нет. В простом варианте Chatcode подключается к DigitalOcean и создаёт Linux-дроплет, на котором для вас работает шлюз. В варианте со своим сервером тот же шлюз устанавливается на Linux-сервер или Mac, который у вас уже есть.

Почему macOS пишет, что chatcode-gateway запрашивает доступ к «Документам», «Загрузкам» или экрану?

На macOS шлюз работает от имени вашего пользователя, поэтому у агента для программирования, которым вы управляете (Claude Code, Codex и т. д.), тот же доступ к файлам, что и у вас. Когда агент читает защищённую папку или пользуется защищённой возможностью системы, macOS показывает стандартный запрос конфиденциальности и приписывает его процессу, который запустил агента, — шлюзу. Это ваш агент делает то, о чём вы попросили, а macOS просто спрашивает согласие обычным для себя способом. Разрешайте то, чего ожидаете, и отклоняйте остальное.

Открывает ли шлюз порты на моей машине?

Входящих портов нет. Шлюз устанавливает исходящее TLS-соединение по WebSocket с управляющим слоем Chatcode, а управляющий слой ретранслирует трафик из вашего браузера и Telegram. (SSH для отладки — отдельная возможность, которая включается только по вашему желанию.)

Может ли Chatcode видеть мой терминальный трафик?

При передаче — да. Трафик шифруется TLS на каждом участке, но сквозного шифрования между вашим браузером и шлюзом нет — так задумано. Управляющий слой обрабатывает содержимое сессий, чтобы работал интерфейс в Telegram (форматирование вывода агента, превью файлов, расшифровка голоса, уведомления), поэтому он выступает доверенным ретранслятором и может читать содержимое терминала. Ваш код, ключи и сессии агентов по-прежнему находятся только на вашей машине; чтобы контролировать и ретранслятор, разверните его у себя.

Зачем шлюзу sudo без пароля на Linux?

Чтобы агент, которым вы управляете, мог выполнять административные задачи (установить пакет, перезапустить службу), не застревая на запросе пароля, на который вы не можете ответить удалённо. На Linux шлюз работает от имени отдельного пользователя vibe, и каждая команда sudo записывается в принадлежащий root журнал только для дозаписи, который вы можете просмотреть.