DarwinRelay

Нативный runtime для macOS для MCP-агентов: shell, PTY, фоновый Chrome и управление рабочим столом через Accessibility.

DarwinRelay подключает MCP-клиент к тому Mac, которым вы уже пользуетесь. Он предоставляет структурированные возможности локальной машины, не встраивая ещё один модельный цикл между клиентом и macOS: неограниченный доступ к shell и файловой системе, интерактивные PTY, длительные задачи, сохранённая история Codex, управляемое фоновое рабочее пространство Chrome и нативное управление рабочим столом через Accessibility, ScreenCaptureKit, Vision и CoreGraphics.

[!CAUTION] DarwinRelay намеренно обладает широкими полномочиями. Это не песочница, и в нём не реализован список разрешённых команд файловой системы или shell. Подключённый клиент может действовать с эффективными правами пользователя macOS, запустившего мост. Прочтите SECURITY.md, прежде чем открывать доступ за пределами localhost.

Зачем нужен DarwinRelay

Многие MCP-серверы предоставляют один узкий API. DarwinRelay спроектирован как локальный runtime для сценариев разработчика и computer-use, где полезное состояние уже живёт на Mac:

• Shell и файлы — запуск команд, просмотр и изменение файлов, применение патчей, управление локальными процессами.

• Настоящие PTY — интерактивные shell, REPL, SSH, запросы sudo, TUI и длительные терминальные программы.

• Нативное computer use — семантические AX-запросы и действия, окна, диалоги, панели открытия/сохранения, запасной ввод с клавиатуры и мыши, скриншоты, OCR и визуальные ожидания.

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

• История Codex — чтение сохранённых потоков Codex без запуска нового витка модели.

• Удалённый MCP-транспорт — stdio локально или встроенный аутентифицированный HTTP/OAuth-фронтенд за туннелем, которым вы управляете.

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

Related MCP server: mcp-server-macos-use

Архитектура

flowchart LR
    A[MCP client] --> B[DarwinRelay bridge]
    B --> C[Shell / filesystem / jobs]
    B --> D[PTY helper]
    B --> E[Codex persisted history]
    B --> F[MacUIHelper]
    F --> G[Accessibility / ScreenCaptureKit / Vision / CGEvent]
    B --> H[Chrome native host]
    H --> I[DarwinRelay Chrome extension]
    I --> J[Background DR tab pool]

Нативный вспомогательный компонент рабочего стола намеренно недолговечен, а не является привилегированным демоном. Приложение в меню, MacUIHelper и виртуальный курсор используют стабильные идентификаторы подписи кода, чтобы гранты macOS TCC переживали обычные пересборки при наличии постоянной подписи.

Требования

• macOS 13 или новее

• Node.js 18 или новее (в CI используется Node.js 22)

• Xcode Command Line Tools / swiftc для нативного управления рабочим столом и приложения в меню

• Разрешения Accessibility и Screen Recording для нативного computer use

• Google Chrome — только если нужен управляемый фоновый workspace chrome_*

• cloudflared или другой HTTPS-туннель — только если вы открываете HTTP-транспорт удалённо

• Codex CLI — только если нужны инструменты истории codex_thread_*

Быстрый старт

Клонируйте репозиторий и соберите приложение в меню:

git clone https://github.com/dcierra/darwinrelay.git
cd darwinrelay
npm run check
./menubar/build.sh
open /Applications/DarwinRelay.app

Приложение появится в строке меню macOS как DR. Предоставьте запрошенные разрешения рабочего стола, затем используйте Start для пути HTTP/туннеля, который вы настроили.

Для локального использования MCP только из исходников мост также можно запустить напрямую. Полный доступ должен быть явно подтверждён:

export DARWINRELAY_FULL_ACCESS_ACK=I_UNDERSTAND_THIS_GRANTS_FULL_ACCESS
node bridge.mjs

Состояние runtime по умолчанию хранится в:

~/Library/Application Support/DarwinRelay
~/Library/Logs/DarwinRelay

Используйте переменные окружения, такие как DARWINRELAY_DATA_DIR, DARWINRELAY_LOG_DIR, DARWINRELAY_SHELL и DARWINRELAY_AUDIT_MODE, чтобы изолировать экземпляры разработки и тестирования.

Для ИИ и агентов кодинга

Этот репозиторий намеренно включает документацию, ориентированную на агентов. Если вы передадите репозиторий Codex, Claude, ChatGPT или другому агенту кодинга, укажите ему на AGENTS.md в первую очередь. Этот файл описывает карту репозитория, инварианты, команды разработки, ожидания по тестированию, правила подписи/браузера и ограничения релизов.

Для агента, работающего с уже установленным runtime DarwinRelay, а не изменяющего исходники, используйте docs/AGENT_OPERATIONS.md. В нём содержится полная карта семейств инструментов, предпочтительный порядок принятия решений, частые состояния сбоев и безопасные рабочие процессы runtime. docs/ARCHITECTURE.md описывает потоки данных компонентов и границы доверия для более глубоких рассуждений.

Нативное управление рабочим столом

DarwinRelay предпочитает семантические операции Accessibility и использует визуальный/сырой ввод как запасной вариант. Основные возможности включают:

• ui_observe, ui_tree, ui_ax_query, ui_ax_at

• фингерпринтованные AX-ссылки с обнаружением устаревших ссылок

• ui_action, ui_wait_for, ui_assert

• ui_app_*, ui_window_*, диалоги и файловые панели

• скриншоты ScreenCaptureKit и Vision OCR

• фоновый ввод, нацеленный на PID, там, где macOS это поддерживает, с семантической проверкой и ограниченным запасным вариантом с фокусом

• ui_sequence для детерминированных многошаговых нативных серий

• кликабельный виртуальный ИИ-курсор, который не двигает физический указатель

См. docs/DESKTOP_CONTROL.md о модели управления и ограничениях.

Фоновое рабочее пространство Chrome

DarwinRelay использует распакованное расширение Chrome плюс Native Messaging. Публичный идентификатор расширения стабилен; ожидаемый id расширения:

pfhahlehpahegefejooendokpkklgmgd

Установщик создаёт или переиспользует вышедший из аккаунта локальный профиль Chrome с именем DarwinRelay по умолчанию. Это держит состояние браузинга агента отдельно от повседневного профиля Google:

# Recommended/default: dedicated local profile named DarwinRelay
./scripts/install-background-chrome.sh

# Explicit alternatives only when you want them
./scripts/install-background-chrome.sh --profile 'Some Existing Profile'
./scripts/install-background-chrome.sh --use-current-profile

Профиль по умолчанию создаётся без удаления или изменения данных браузинга в других профилях. Если профиля DarwinRelay ещё нет, закройте Chrome один раз перед запуском установщика, чтобы Chrome не мог параллельно перезаписать свой Local State; после создания профиля обычные переустановки можно выполнять при открытом Chrome. Удаление DarwinRelay намеренно оставляет этот профиль на месте, поскольку содержимое профиля браузера — это пользовательские данные.

Затем только в выбранном профиле откройте chrome://extensions, включите режим разработчика, выберите Load unpacked и укажите каталог chrome-extension/ этого репозитория. Можно передать --open установщику для этого одноразового шага настройки.

Расширение владеет нативной группой вкладок Chrome с именем DR. Обычные вызовы chrome_open арендуют заранее созданные простаивающие вкладки вместо создания произвольных вкладок на переднем плане. chrome_close возвращает вкладки рабочего пространства в пул.

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

Ослабленные разрешения — это значение по умолчанию. Обычная работа с HTTP/HTTPS через настроенный workspace chrome_* не требует терминального гранта на каждый сайт. Включение Strict approvals в приложении в меню восстанавливает ограниченные URL-гранты и одноразовые гранты на нативные изменения в рамках приложения.

Прямая автоматизация Chrome через shell/AppleScript/JXA остаётся заблокированной мостом, чтобы обычная веб-работа оставалась на управляемом фоновом пути. Отдельная нативная поверхность ui_* по-прежнему может взаимодействовать с Chrome на переднем плане, когда поверхности безопасности браузера/ОС действительно этого требуют.

Опциональный сырой адаптер Browser Harness/CDP существует за DARWINRELAY_ADVANCED_BROWSER=1. Он отключён по умолчанию и закрывается при Strict approvals, поскольку произвольный CDP нельзя обоснованно свести к URL-областям.

HTTP / OAuth-транспорт

mcp-http.mjs привязывается к loopback и поддерживает MCP HTTP-транспорт со статическим bearer-токеном плюс потоки OAuth 2.1, используемые удалёнными MCP-клиентами. Туннель, такой как Cloudflare, может опубликовать loopback-сервис через HTTPS.

Минимальный локальный фронтенд выглядит так:

mkdir -p "$HOME/Library/Application Support/DarwinRelay"
openssl rand -hex 32 > "$HOME/Library/Application Support/DarwinRelay/http-token"
chmod 600 "$HOME/Library/Application Support/DarwinRelay/http-token"

export DARWINRELAY_HTTP_TOKEN_FILE="$HOME/Library/Application Support/DarwinRelay/http-token"
node mcp-http.mjs

Не открывайте HTTP-эндпоинт, не прочитав модель угроз удалённого доступа в SECURITY.md. Учётные данные, принятые этим фронтендом, в конечном счёте открывают локальное выполнение кода от имени вашего пользователя рабочего стола.

Репозиторий также сохраняет установщик OpenAI Secure MCP Tunnel, унаследованный от исходного проекта, для пользователей, предпочитающих этот транспорт. См. DEPLOY.md.

Разработка

npm run check
npm run test:core
npm run test:desktop
npm run test:lifecycle
# or all groups
npm test

Публичный CI намеренно показывает отдельные проверки вместо одного непрозрачного задания test:

• Статические проверки — проверка синтаксиса/нативной сборки и полное сканирование gitleaks по истории

• Тесты ядра и протокола — MCP, HTTP/OAuth, PTY, федерация, браузер и состязательные тесты

• Тесты управления рабочим столом — детерминированные тесты протокола рабочего стола плюс компиляция нативных фикстур

• Тесты установки и жизненного цикла — установщики, автозапуск, владение одиночным экземпляром, откат и поведение при удалении

Настоящий изменяемый E2E AppKit требует вошедшего в систему Mac с разрешениями TCC и поэтому не считается надёжным на одноразовых GUI-сессиях GitHub. Мейнтейнеры могут запускать его локально с помощью:

DARWINRELAY_RUN_NATIVE_DESKTOP_E2E=1 node tests/desktop-control-native.mjs

См. CONTRIBUTING.md перед открытием pull request.

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

Важная граница проста: DarwinRelay обладает полномочиями учётной записи macOS, под которой он запущен. Такие функции безопасности, как файл разблокировки, Strict approvals, метаданные аудита, OAuth, маршрутизация фонового браузера и возврат процессов, снижают случайное или удалённое злоупотребление; они не превращают произвольный доступ к shell в песочницу.

Сообщения об уязвимостях следует отправлять через приватную систему отчётов GitHub, а не через публичный issue. См. SECURITY.md.

Происхождение проекта

DarwinRelay поддерживается независимо и существенно разошёлся с Mac Developer Bridge Александра Родаля Бенца. Унаследованная история апстрима намеренно сохранена, и исходное уведомление об авторских правах MIT остаётся в LICENSE. См. UPSTREAM.md о точном происхождении и политике атрибуции.

Публичный репозиторий dcierra/darwinrelay — канонический источник разработки. Предыдущий приватный репозиторий сохраняется только как временная линия наследования для продакшена/отката, пока установленный runtime 0.5.x не будет мигрирован; это не вторая активная ветка разработки. См. docs/DEVELOPMENT_MODEL.md о сопоставлении истории коммитов и будущем рабочем процессе.

DarwinRelay не аффилирован с OpenAI, Apple, Google, Cloudflare или мейнтейнером апстрима и не одобрен ими.

Лицензия

MIT. См. LICENSE и UPSTREAM.md.