RepoRelay

Что делает RepoRelay

RepoRelay — это локальный, собственный MCP-мост, который предоставляет ChatGPT ограниченный доступ ровно к одному одобренному репозиторию на вашем компьютере — и не более того.

ChatGPT просматривает ваш код через RepoRelay и может оставить структурированную задачу для отдельного локального агента кодирования (например, Codex или Claude) через фиксированные файлы handoff. RepoRelay — это граница безопасности между ChatGPT и вашей машиной.

ChatGPT reviews/plans
        ↓
RepoRelay
        ↓
Repository reads/searches
+
fixed .ai-handoff writers
        ↓
Codex / another local coding agent implements

Related MCP server: codex-web-bridge

Как работает модель безопасности

MCP (Model Context Protocol) — это стандарт, позволяющий ChatGPT вызывать инструменты. ChatGPT является MCP-клиентом. RepoRelay — локальный MCP-сервер и граница безопасности: он решает, к чему ChatGPT может получить доступ, и показывает ровно один одобренный репозиторий за раз. tunnel-client — это только защищённый сетевой канал, передающий трафик ChatGPT на ваш компьютер.

Что ChatGPT может делать через RepoRelay (обычная конфигурация с 7 инструментами):

✓ inspect files          open_workspace, list_files, read_file
✓ search the repository  search_files
✓ write to three predetermined handoff targets
                         write_next_task, write_review, update_handoff_state

Что ChatGPT не может делать:

✗ run shell commands
✗ run PowerShell
✗ run Git
✗ launch processes
✗ arbitrarily edit source files
✗ delete files
✗ choose arbitrary write targets
✗ access outside the approved repository

Это одно из самых сильных отличий RepoRelay: ChatGPT может читать и планировать действия с вашим кодом, но не получает возможности выполнения и может записывать только в несколько фиксированных файлов handoff, которые вы контролируете.

Перед установкой

Вам потребуется:

• Node.js версии >=22.19 и <27 (npm входит в комплект). Проверьте с помощью node --version.

• Существующий локальный проект или репозиторий, который вы хотите показать ChatGPT. Это должна быть реальная папка на вашем компьютере — не корень диска и не вся ваша пользовательская папка.

• Доступ к Secure MCP Tunnel от OpenAI. RepoRelay связывается с ChatGPT через Secure MCP Tunnel от OpenAI. Информацию о доступности, разрешениях и тарифах см. в актуальном руководстве OpenAI по Secure MCP Tunnel.

• Разрешение на создание/использование пользовательского MCP-приложения в целевом рабочем пространстве ChatGPT (режим разработчика ChatGPT).

Вам не нужно скачивать что-либо ещё. RepoRelay автоматически устанавливает официальный tunnel-client от OpenAI во время выполнения reporelay tunnel setup.

Пока не беспокойтесь о протоколе handoff. Краткое руководство создаёт рабочие файлы handoff и объясняет их по ходу дела.

Быстрая настройка

Пути в Windows. Всегда заключайте полный путь в кавычки и сохраняйте обратные слеши:

reporelay quickstart "C:\Users\you\Projects\my-app"

C:\Users\you\Projects\my-app — правильно. C:Users\you\Projects\my-app — неправильно: обратные слеши важны.

1. Установка RepoRelay

npm install -g reporelay-mcp@latest

Проверьте установку:

reporelay --version

Если reporelay не распознаётся, см. Устранение неполадок.

2. Запуск RepoRelay на одном репозитории

reporelay quickstart "C:\Projects\my-app"

Замените путь на репозиторий, который вы хотите открыть. Оставьте это окно PowerShell открытым.

Вы должны увидеть:

Ready.
Local MCP: http://127.0.0.1:7676/mcp

Обычное краткое руководство включает поверхность handoff с 7 инструментами (4 инструмента проверки + 3 фиксированных обработчика записи). Теперь RepoRelay создаёт небольшое рабочее пространство .ai-handoff и заметку AGENTS.md, чтобы ChatGPT мог оставлять структурированные задачи и рецензии для отдельного локального агента кодирования:

.ai-handoff/NEXT_TASK.md
.ai-handoff/REVIEW.md
.ai-handoff/RESULT.md
.ai-handoff/STATE.json
AGENTS.md

Зачем RepoRelay их создаёт? ChatGPT по-прежнему не может запускать команды, использовать Git или произвольно редактировать ваш репозиторий. Эти файлы — просто место, где ChatGPT может оставить задачу, а отдельный локальный агент кодирования (работающий на вашей машине с вашего разрешения) может оставить свой результат. Подробнее ниже в разделе ChatGPT ↔ агент кодирования: handoff.

Чтобы остановить RepoRelay позже, нажмите Ctrl+C в этом окне. Команды reporelay quickstart --stop не существует.

3. Аудит

Сразу после краткого руководства проверьте фактическую границу безопасности RepoRelay:

reporelay audit "C:\Projects\my-app"

Вы должны увидеть:

RESULT: PASS

Аудит запускает собственный временный loopback-слушатель и проверяет реальную аутентифицированную MCP-поверхность, проверки изоляции и ограничения handoff. Он не изменяет ваш репозиторий. Это подтверждает RepoRelay до подключения ChatGPT.

4. Запуск настройки туннеля RepoRelay

В новом окне PowerShell выполните:

reporelay tunnel setup

Это запускает мастер настройки RepoRelay. Он делает всё за вас:

✓ installs a RepoRelay-supported OpenAI tunnel-client
✓ verifies it (pinned version + official SHA-256)
✓ opens OpenAI tunnel setup
✓ asks for your tunnel ID
✓ opens OpenAI runtime-key setup
✓ securely stores the pasted key
✓ creates the tunnel profile
✓ tests the complete connection

Вы предоставляете ровно две вещи, обе на платформе OpenAI:

1. ID вашего Secure MCP Tunnel — мастер открывает https://platform.openai.com/settings/organization/tunnels в вашем браузере. Создайте или выберите туннель, свяжите его с вашим рабочим пространством ChatGPT и вставьте его tunnel_id обратно в терминал.

2. Ключ API времени выполнения — мастер открывает https://platform.openai.com/settings/organization/api-keys. Создайте секретный ключ для проекта, который вы используете с туннелем, и вставьте его в терминал. Ввод скрыт: при вставке ничего не отображается. Этот ключ аутентифицирует tunnel-client перед OpenAI; это не секрет моста RepoRelay.

Создание или редактирование туннеля требует разрешения Tunnels Read + Manage; запуск tunnel-client или выбор туннеля требует Tunnels Read + Use. Это разрешения на уровне организации, предоставляемые владельцем организации или администратором RBAC. Следуйте актуальному руководству OpenAI по Secure MCP Tunnel для точной информации об интерфейсе и разрешениях.

Когда мастер завершится, вы должны увидеть:

Testing connection...
✓ OpenAI runtime credential
✓ RepoRelay reachable
✓ Bridge authentication

Setup complete.

Next:
  reporelay tunnel run

Эти проверки реальны: настройка проверяет ключ API времени выполнения на панели управления OpenAI (тот же поиск туннеля только для чтения, который tunnel-client выполняет при запуске) и проверяет секрет моста на фактически работающий RepoRelay. Неправильный, истёкший или неверно вставленный ключ будет обнаружен здесь с понятным сообщением — а не после запуска tunnel run.

Если ваш RepoRelay работает на пользовательском порту (например, --port 7677), краткое руководство уже записало работающую конечную точку, и настройка следует за ней автоматически — никаких дополнительных флагов не нужно.

Полезные опции:

• reporelay tunnel setup --no-open — не открывать браузер (безголовый режим, SSH или CI); URL-адреса всё равно выводятся.

• reporelay tunnel setup --replace-tunnel — запросить новый ID туннеля.

• reporelay tunnel setup --replace-runtime-key — запросить новый ключ API времени выполнения.

• reporelay tunnel setup --tunnel-client-path "C:\custom\tunnel-client.exe" — продвинутое переопределение для нестандартных окружений; RepoRelay не проверяет и не управляет пользовательским бинарным файлом.

Повторный запуск reporelay tunnel setup повторно использует существующий проверенный клиент, ID туннеля и сохранённый ключ, и снова тестирует соединение, не запрашивая ничего заново.

5. Запуск туннеля

reporelay tunnel run

Оставьте это окно открытым рядом с окном краткого руководства RepoRelay. Остановите его с помощью Ctrl+C, когда закончите.

Если соединение перестало работать, команда reporelay tunnel doctor остаётся доступной как отдельная команда для устранения неполадок (ожидается сообщение Ready., когда всё в порядке; добавьте --verbose для диагностики с удалением конфиденциальных данных).

6. Создание приложения ChatGPT

В ChatGPT, используя текущий поток OpenAI (см. руководство по режиму разработчика ChatGPT и MCP-приложениям):

ChatGPT
→ Apps / developer features
→ create custom MCP app
→ connection: Tunnel
→ choose RepoRelay's tunnel
→ authentication: No authentication
→ Scan Tools
→ verify 7 tools
→ create/use the app
→ start a new chat

Следуйте этой последовательности:

1. Создайте пользовательское MCP-приложение.

2. Выберите соединение Tunnel.

3. Выберите RepoRelay/OpenAI Secure MCP Tunnel.

4. Когда ChatGPT запросит аутентификацию, выберите No authentication.

5. Сохраните или создайте приложение.

6. Выполните Scan Tools.

7. Убедитесь, что отображаются ожидаемые инструменты RepoRelay.

8. Начните новый чат и выберите приложение RepoRelay.

Аутентификация: No authentication. RepoRelay уже аутентифицирует локальный мост через защищённый X-RepoRelay-Bridge-Secret, используемый туннелем. Не настраивайте OAuth или другой метод аутентификации со стороны ChatGPT.

Никогда не вставляйте 127.0.0.1, localhost, секрет моста RepoRelay или ключ API времени выполнения OpenAI в ChatGPT. Туннельное соединение выполняет всю сетевую работу.

7. Сканирование и проверка 7 инструментов RepoRelay

В потоке приложения ChatGPT выполните Scan Tools и подтвердите, что RepoRelay предоставляет ровно эти семь инструментов:

open_workspace
list_files
read_file
search_files
write_next_task
write_review
update_handoff_state

Это ожидаемая стандартная поверхность. Если Scan Tools показывает shell, Git, выполнение процессов, общее редактирование файлов, удаление, патчинг или любую другую неожиданную возможность, остановитесь и проверьте, прежде чем использовать приложение — выполните reporelay audit "C:\Projects\my-app" --json и проверьте список инструментов.

8. Тестирование

Начните новый чат, выберите приложение RepoRelay и попробуйте:

Open the approved repository and list its top-level files.

Затем проверьте границу:

Try to read .env.

Второй запрос должен быть заблокирован.

Вы подключены — что дальше?

Теперь ChatGPT просматривает ваш репозиторий через проверенную границу безопасности. Полезные запросы:

Read README.md and explain how this project starts.

Search the repository for "authentication".

Review src/server.ts for error-handling issues and write your findings.

ChatGPT ↔ агент кодирования: handoff

Обычная конфигурация RepoRelay позволяет ChatGPT планировать и рецензировать, в то время как отдельный локальный агент кодирования (Codex, Claude или другой) выполняет реализацию. RepoRelay координирует их через небольшое рабочее пространство .ai-handoff:

.ai-handoff/
├── NEXT_TASK.md   ChatGPT writes the task here
├── RESULT.md      the local coding agent writes its result here
├── REVIEW.md      ChatGPT writes its review here
└── STATE.json     coordinates the cycle

Концептуально:

ChatGPT
  ↓ writes NEXT_TASK.md

Codex / local coding agent
  ↓ implements
  ↓ writes RESULT.md

ChatGPT
  ↓ reviews result
  ↓ writes REVIEW.md

STATE.json координирует цикл. Сам RepoRelay не запускает Codex или Claude — это отдельные локальные приложения, которые вы запускаете сами. Файлы handoff — это просто структурированное место для передачи работы друг другу.

ChatGPT может записывать только NEXT_TASK.md, REVIEW.md и STATE.json. Файл RESULT.md, принадлежащий исполнителю, никогда не доступен для записи ChatGPT.

См. docs/handoff-cycle.md для подробного описания протокола и examples/ для примеров промптов ревьюера и исполнителя.

Ежедневное использование

После первоначальной настройки не пересоздавайте туннель и приложение ChatGPT. Каждый день:

1. Запустите RepoRelay:

   reporelay quickstart "C:\Projects\my-app"

2. Запустите туннель (во втором окне):

   reporelay tunnel run

3. Откройте ChatGPT, начните новый чат и выберите существующее приложение RepoRelay.

Держите оба окна открытыми, пока используете приложение. Если соединение перестанет работать, снова выполните reporelay tunnel doctor.

Смена репозиториев

RepoRelay работает с одним репозиторием за раз.

1. Нажмите Ctrl+C в терминале RepoRelay.

2. Запустите RepoRelay для нового репозитория:

   reporelay quickstart "C:\Projects\another-repo"

3. Оставьте tunnel-client запущенным. Он автоматически переподключается к перезапущенному RepoRelay (тот же порт и защищённый файл bridge-secret). Если вы использовали другой порт, управляемый туннель следует за ним автоматически.

4. Начните новый разговор в ChatGPT и выберите приложение RepoRelay.

5. Попросите ChatGPT открыть новый репозиторий.

Не сканируйте инструменты заново только потому, что одобренный репозиторий изменился. Сканируйте заново только если изменились определения инструментов или ChatGPT попросит вас об этом.

Для всего остального запустите reporelay doctor. Он выводит статус конфигурации и безопасности без вывода секретных значений.

Необязательный режим только для чтения

Обычный опыт работы с RepoRelay — это поверхность передачи из 7 инструментов, описанная выше, и это рекомендуемая настройка для начинающих. Если вы хотите, чтобы ChatGPT только просматривал — без файлов передачи, без записи вообще — начните с:

reporelay quickstart "C:\Projects\my-app" --no-handoff-writes

В этом необязательном режиме RepoRelay предоставляет ровно четыре инструмента:

open_workspace
list_files
read_file
search_files

Режим только для чтения не создает .ai-handoff, не создает и не изменяет AGENTS.md и оставляет одобренный репозиторий без изменений. Все проверки изоляции, аутентификации и безопасности по-прежнему применяются. Используйте соответствующий флаг аудита:

reporelay audit "C:\Projects\my-app" --no-handoff-writes

При использовании этого режима ожидайте 4 инструмента в Scan Tools вместо 7.

Безопасность

Принудительная граница RepoRelay включает:

• привязка только к loopback и обязательная аутентификация;

• ровно один существующий канонический одобренный корень;

• блокировка чувствительных путей, включая .env, метаданные VCS, хранилища учетных данных и форматы закрытых ключей;

• блокировка обхода, абсолютных путей за пределами корня, обхода симлинков/переходов/reparse и обхода жестких ссылок;

• ограниченные чтения, поиски, результаты и содержимое передачи;

• отсутствие инструментов shell, PowerShell, Git, процессов, общей записи, патчей, удаления, артефактов, рабочего дерева, навыков, субагентов или локальных агентов;

• запись передачи ограничена тремя фиксированными предварительно существующими целями.

RepoRelay — это граница приложения с минимальными привилегиями, а не песочница операционной системы против вредоносного ПО, уже работающего от имени того же локального пользователя. Внешний Secure MCP Tunnel — это отдельная граница безопасности, которую необходимо защищать независимо. Выбирайте одобренный репозиторий тщательно.

См. SECURITY.md для полной модели безопасности и документацию reporelay audit.

Расширенная конфигурация

Большинству пользователей это никогда не нужно. Когда нужно:

• Конфигурация — переменные окружения REPORELAY_*, аутентификация моста, порты, журналирование и режим передачи.

• Детали настройки ChatGPT Web — полный справочник по туннелю и приложению.

• Операции Windows — скрипты жизненного цикла, запланированные задачи и управляемая настройка Windows.

• .env.example — только пример конфигурации. Никогда не помещайте в него реальный секрет моста или учетные данные туннеля.

• Локальные MCP-клиенты — если ваш MCP-клиент работает на том же компьютере, что и RepoRelay, туннель не нужен: укажите ему локальный MCP URL, выведенный в quickstart, и отправьте заголовок X-RepoRelay-Bridge-Secret, загруженный из защищенного файла.

Для статуса конфигурации и безопасности без вывода секретных значений:

reporelay doctor

Требования и поддержка платформ

• Node.js >=22.19 <27 (npm включен);

• Git для установки на основе клонирования — необязательно, если вы загружаете ZIP вместо этого.

Quickstart в этом README работает на Windows, macOS и Linux. Windows 10/11 — полностью проверенная платформа жизненного цикла и операций, включая скрипты PowerShell и управляемый туннелем runbook.

Ограничения

• Одновременно предоставляется один одобренный репозиторий.

• RepoRelay не является песочницей операционной системы.

• ChatGPT Web требует внешней инфраструктуры OpenAI Secure MCP Tunnel для доступа к частному локальному мосту.

• Windows — полностью проверенная платформа жизненного цикла; другие платформы не имеют идентичных операций PowerShell/туннеля.

• Codex, Claude и другие кодинг-агенты — это отдельные локальные приложения, а не компоненты RepoRelay.

Документация

• Настройка ChatGPT Web

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

• Конфигурация

• Операции Windows

• Заметки по установке

• Цикл передачи

• Примеры передачи

• Вклад

Лицензия и происхождение проекта

RepoRelay выпущен под лицензией MIT. Проект сохраняет требуемую атрибуцию вышестоящего проекта и не включает SDK или среды выполнения Codex, Claude или других реализаторов.

Разработка

npm ci
npm run typecheck
npm test
npm run verify:release
npm audit --audit-level=low
npm pack --dry-run --json
git diff --check