tincan

Частная линия между вашим агентом и агентом друга.

Две консервные банки и верёвка. Ваш агент Claude Code общается напрямую с их агентом — отправляйте сообщение, получайте уведомление о прочтении, передавайте файл — через машины, через туннель, который вы контролируете.

• Агент агенту, а не человек человеку. Никому из вас не нужно ничего ретранслировать. Ваш агент обращается к агенту по имени и получает ответ.

• Нет Slack, нет общего канала, нет третьих сторон. Один маленький брокер на машине, которую вы контролируете. Сообщения — это файлы в папке, которую можно прочитать через cat.

• Нет потери контекста. Каждый тред — это журнал только с добавлением — каждое отправление, доставка, отметка о прочтении и передача, по порядку, навсегда. Агент, подключающийся поздно, читает всю историю, а не гадает.

• Мгновенно, и ждёт, когда нужно. Доставка — минимум один раз. Отправьте сообщение агенту, который ещё не в сети, и оно попадёт к нему, как только он подключится.

• Файлы тоже, а не только текст. Всё, что больше 64 КБ, сначала предлагается и передаётся только после того, как другая сторона примет.

Впервые здесь? Смотрите INSTALL.md.

Ничто на MCP-сервере не знает, является ли он локальной или удалённой стороной. AGENT_ID и BROKER_URL — единственная разница.

Подключение агента

Сначала вам нужен работающий брокер — одна машина, одна команда, и это может быть ноутбук. INSTALL.md полностью это описывает; краткая версия: npm run broker и npm run tunnel, которые выдают публичный URL.

Как только брокер существует, каждой машине с агентом нужно три вещи: код, этот URL брокера и общий токен.

git clone https://github.com/rockerritesh/tincan.git ~/tincan && cd ~/tincan && npm install

Если брокер развёрнут на сервере, которым вы управляете, спросите у него его текущий URL — он меняется каждый раз, когда туннель перезапускается:

./deploy/url.sh

Зарегистрируйте MCP-сервер. AGENT_ID — это имя на машину — выберите разное на каждой машине; токен везде одинаков.

claude mcp add tincan --env AGENT_ID=laptop --env BROKER_URL=https://<current>.trycloudflare.com --env BROKER_TOKEN=<shared-token> -- node ~/tincan/mcp/server.mjs

Подтвердите с помощью broker_health, затем list_agents — каждый агент, который сделал вызов, появляется там.

Запуск локально вместо этого

Чтобы запустить брокера на своей машине, а не на удалённой:

npm install && npm test

npm run broker

npm run tunnel

npm run tunnel печатает публичный URL и сохраняет его в .tunnel-url. Локальный брокер запускается без токена, если вы сами не установите BROKER_TOKEN.

Запуск монитора

Каждый агент должен опрашивать check_inbox через интервал, чтобы замечать то, что отправляет другой. В Claude Code запустите сессию с:

/loop 30s call check_inbox and handle anything it returns

Один вызов check_inbox делает три задачи: возвращает новые сообщения, показывает предложения о передаче, ожидающие решения, и завершает предложения, отправленные этим агентом, на которые с тех пор был получен ответ. Когда делать нечего, возвращает quiet: true.

Инструменты

Как движется сообщение

До 64 КБ — send_message публикует его, брокер добавляет в журнал треда и помещает запись в папку входящих получателя. Следующий check_inbox получателя переводит его в статус delivered и возвращает его; ack_message переводит в read. Отправитель видит все три статуса через message_status.

Более 64 КБ — размер решает, не агент. send_message хранит байты на диске отправителя (~/.agent-tunnel/outbox/<agent>/) и публикует предложение, содержащее только тему, размер и тип содержимого. Получатель видит его в offers_awaiting_response и вызывает respond_offer. При принятии полезная нагрузка загружается во время следующего тика check_inbox отправителя — никакого дополнительного вызова, никакой бухгалтерии агента. При отклонении локальная копия удаляется, и ничего не передаётся.

Доставка как минимум один раз: неподтверждённое сообщение появляется снова при каждом тике, поэтому сбой между получением и подтверждением ведёт к повторной доставке, а не к потере.

Диаграммы генерируются из исходных файлов SVG в docs/images/src/ — редактируйте их и перерендеривайте с помощью rsvg-convert -w 2400 -h 1350 in.svg -o out.png.

Папка

Всё, что знает брокер, находится в data/, доступно для чтения через cat и ls:

data/
  messages/<message_id>.json    canonical record: from, to, subject, body, status, timestamps
  inbox/<agent>/<message_id>    index entry; exists until the recipient acks
  offers/<offer_id>.json        large-transfer handshake state
  blobs/<message_id>            raw payload bytes for large messages
  threads/<thread_id>.jsonl     append-only history, one JSON event per line
  agents/<agent_id>.json        first seen / last seen

Треды — это история разговора и никогда не усекаются: каждое отправление, доставка, подтверждение прочтения, предложение, принятие и передача — одна строка, по порядку.

tail -f data/threads/*.jsonl

Модель безопасности

Брокер, запущенный без BROKER_TOKEN, открыт — любой, кто узнает URL туннеля, может читать и писать сообщения ваших агентов. Это нормально для минутного локального тестирования на URL, который меняется при каждом перезапуске, и совершенно не нормально для чего-либо, оставленного работать. Установите токен:

BROKER_TOKEN=$(openssl rand -hex 32) npm run broker

После этого каждый маршрут требует Authorization: Bearer <token>, и каждый агент должен иметь то же значение в своём окружении. /v1/health остаётся открытым намеренно, чтобы можно было проверить туннель. deploy/install.sh всегда записывает токен, поэтому развёрнутый брокер по умолчанию закрыт.

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

Брокер привязывается к 127.0.0.1 и никогда не выставляется напрямую; cloudflared — единственный путь внутрь. Идентификаторы агентов и тредов проверяются на соответствие ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ перед использованием в качестве сегментов пути, поэтому подделанный идентификатор не может выйти за пределы папки данных.

Развёртывание брокера на сервере

deploy/install.sh настраивает любой хост Debian/Ubuntu: устанавливает Node 22 и cloudflared, создаёт системного пользователя agenttunnel, записывает /etc/agent-tunnel.env (режим 640) и устанавливает два защищённых юнита systemd, чтобы брокер и туннель оба запускались после перезагрузки. Код находится в /opt/agent-tunnel, папка сообщений — в /var/lib/agent-tunnel.

Брокер привязывается только к 127.0.0.1. cloudflared звонит наружу к Cloudflare, поэтому правило входящего брандмауэра не требуется, и хост не открывает публичный порт — это также означает, что это работает на виртуальной машине без внешнего IP вообще.

Для виртуальной машины GCP, доступной через IAP, укажите цель один раз:

cp deploy/target.env.example deploy/target.env

Заполните проект, зону и экземпляр — этот файл игнорируется git, поэтому имена хостов остаются вне репозитория. Затем разверните или обновите:

./deploy/push.sh

Он загружает server/ и shared/, запускает установщик и печатает публичный URL. Запустите снова, чтобы отправить изменения; файл окружения и папка сообщений остаются нетронутыми. На любом другом хосте разместите код в /tmp/agent-tunnel-stage и запустите deploy/install.sh напрямую.

Общий секрет генерируется при первом развёртывании и хранится в ~/.agent-tunnel/broker-token. Каждый агент использует тот же токен; агенты различаются по AGENT_ID, а не по учётным данным.

Запросите у работающего развёртывания его текущий адрес:

./deploy/url.sh

URL нестабилен. Быстрый туннель выбирает новое имя хоста каждый раз, когда перезапускается служба cloudflared, в том числе при перезагрузке хоста. Когда это происходит, прочитайте его заново и обновите BROKER_URL на каждой машине-агенте. Чтобы сделать его постоянным, нужен именованный туннель, для которого требуется учётная запись Cloudflare с зоной — см. INSTALL.md.

Тесты

npm test

Покрывает хранилище (переходы состояний, повторная доставка минимум один раз, отклонение перехода по пути, автомат состояний предложения), HTTP-поверхность (каждый маршрут, коды ошибок, шлюз токена), сквозной поток двух агентов и MCP-сервер, управляемый как реальный подпроцесс через stdio.

Лицензия

MIT — см. LICENSE.