arena-bridge

Облачный ИИ-агент получает управление вашим компьютером — и только с вашего разрешения.

npm i -g arena-bridge  →  arena-bridge setup  →  вставьте готовый промпт в чат с агентом

Что это

Полное дерево функциональности — в feature-tree.md.

Облачный агент (Arena.ai Agent Mode, Claude, Cursor, любой MCP-клиент) работает в песочнице с выходом в интернет, но не имеет доступа к вашему компьютеру. arena-bridge — это маленький HTTP-сервис на вашей машине: он слушает только localhost, выставляется наружу туннелем (cloudflared / ngrok / Tailscale) и отдаёт агенту инструменты, которые вы ему разрешили:

• файлы и шелл — прочитать, найти, изменить, запустить;
• Chrome — свой браузер агента (headless или с окном) или ваш настоящий Chrome на порту 9222;
• macOS-десктоп — скриншоты, мышь, клавиатура, приложения (через Peekaboo);
• процессы — фоновые дев-серверы с чтением вывода.

Всё, что меняет состояние, проходит через гейт подтверждений, а каждое действие пишется в журнал. Без вашего arena-bridge approve агент ничего не сделает. Наблюдать за машиной можно без подтверждений, а работать «без вопросов» — внутри окна доверия, которое вы открываете сами.

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

Одна команда ставит и командную строку, и нативное приложение для macOS:

curl -fsSL https://raw.githubusercontent.com/vernikr/arena-bridge/main/install.sh | sh

Или по отдельности:

npm i -g arena-bridge          # только командная строка
pip install arena-bridge       # то же самое на Python

Приложение macOS можно скачать и без терминала — в каждом выпуске лежат готовые сборки: Apple silicon · Intel. Распаковать и перетащить в «Программы».

# 1. один раз: создать конфиг, проверить машину, поднять API + туннель
arena-bridge setup --root ~/projects --root ~/Documents

# 2. скопировать блок «Paste this into the agent chat» и вставить его в чат с агентом

macOS и Gatekeeper. Приложение подписано локально, поэтому при первом запуске система может сказать «нельзя открыть, так как разработчик не проверен». Обойти это можно без терминала: правый клик по Arena Bridge в «Программах» → Открыть → Открыть. Через терминал: xattr -dr com.apple.quarantine "/Applications/Arena Bridge.app".

setup печатает готовый промпт и публичный URL. Дальше — просто говорите агенту задачу.

Туннель под присмотром: если cloudflared/ngrok упадёт, мост поднимет его заново и сам напечатает новый публичный адрес. Постоянный адрес вместо случайного — arena-bridge tunnel --bin ngrok --domain <зарезервированный домен>.

Нужен туннель? Поставьте cloudflared (brew install cloudflared или бинарник в /usr/local/bin). Можно и через ngrok — arena-bridge tunnel --bin ngrok; с сохранённым токеном и зарезервированным доменом публичный адрес остаётся постоянным, и промпт агенту не нужно копировать заново: arena-bridge tunnel --bin ngrok --authtoken <token> --domain <name>.ngrok-free.dev.

В фоне, чтобы не открывать терминал

Мост можно поднять как службу macOS — он стартует вместе с системой, переживает закрытие терминала и поднимается заново после сбоя:

arena-bridge service install                                   # облако, случайный адрес
arena-bridge service install --bin ngrok --domain mymac.ngrok-free.app   # постоянный адрес
arena-bridge service status                                    # состояние и текущий URL
arena-bridge url                                              # текущий публичный адрес
arena-bridge service uninstall

arena-bridge service install   # launchd: стартует вместе с системой, URL всегда живой
arena-bridge url                # текущий публичный URL

Python

pipx install arena-bridge       # или: pip install arena-bridge
arena-bridge setup --root ~/projects

Что агент умеет

Полный каталог с JSON-схемами: GET /tools или arena-bridge tools.

Как выбрать инструмент

Управление Chrome

Свой минимальный CDP-клиент внутри пакета: ни puppeteer, ни playwright не нужны.

// браузер агента: свой профиль, без ваших cookie
{"tool": "chrome_launch", "args": {"headless": true, "url": "https://example.com"}}
// прочитать структуру страницы
{"tool": "chrome_snapshot", "args": {"mode": "ax"}}
// кликнуть и ввести
{"tool": "chrome_click", "args": {"text": "Sign in"}}
{"tool": "chrome_type", "args": {"selector": "input[name=q]", "text": "hello", "submit": true}}
// скриншот
{"tool": "chrome_screenshot", "args": {"path": "shot.png"}}

• headless: true — без окна (по умолчанию), headless: false — видимое окно;
• профиль отдельный (~/.arena-bridge/chrome-profile-*), в ваши сессии агент не попадает;
• действия в браузере агента подтверждения не требуют — это его песочница.

Ваш настоящий Chrome (с вашими логинами) — через chrome_attach:

open -na "Google Chrome" --args --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-debug"

{"tool": "chrome_attach", "args": {"port": 9222}}

Любое действие в присоединённом браузере требует локального подтверждения. Инструментов чтения cookies и localStorage нет.

Управление macOS-десктопом

Через Peekaboo (это же использует и MCP-режим Peekaboo):

{"tool": "mac_see", "args": {"app": "Safari", "mode": "window"}}  // скриншот + id элементов
{"tool": "mac_element", "args": {"name": "Save"}}                // найти кнопку по названию
{"tool": "mac_click", "args": {"on": "B3"}}                      // клик по id из mac_see
{"tool": "mac_set", "args": {"on": "B2", "value": "hello"}}      // вписать значение напрямую
{"tool": "mac_type", "args": {"text": "hello", "submit": true}}
{"tool": "mac_key", "args": {"key": "cmd+s"}}
{"tool": "mac_menu_click", "args": {"app": "Safari", "item": "Save"}}  // пункт меню по названию
{"tool": "mac_wait", "args": {"name": "Saved", "timeout": 20}}        // дождаться результата
{"tool": "mac_apps", "args": {}}                                  // что запущено
{"tool": "mac_permissions", "args": {}}                           // чего не хватает в macOS

Установить Peekaboo: brew install peekaboo (или бинарник в /usr/local/bin/peekaboo). Проверено с Peekaboo 4.9 (4.3 тоже работает, но синтаксис команд обновлён под 4.9). macOS спросит разрешения Screen Recording и Accessibility для терминала, из которого запущен мост — без них скриншоты и клики не работают; mac_permissions покажет, что не так.

Что даёт доступ Accessibility

macOS отдаёт приложениям два разных слоя: картинку экрана и Accessibility API — дерево элементов интерфейса с названиями, ролями и значениями. Второй слой полезен агенту сильнее:

Практический вывод: с выданным Accessibility агент работает заметно точнее и тише. Разрешение даётся один раз в Системные настройки → Конфиденциальность и безопасность → Универсальный доступ (для терминала, из которого запущен мост). mac_permissions показывает текущее состояние разрешений.

Журнал работы с артефактами

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

arena-bridge audit                 # последние вызовы
arena-bridge audit artifacts       # сохранённые файлы (скриншоты, деревья)
arena-bridge audit <id>            # одна запись целиком
arena-bridge audit prune           # удалить старые артефакты (по умолчанию старше 14 дней)
arena-bridge audit dir             # где всё это лежит

Агенту доступно то же самое: audit_log (вызовы) и audit_artifact (сам артефакт — PNG в base64 или дерево Accessibility в JSON), а также GET /audit и GET /audit/artifact?entry=<id>&file=<name>. Полезно, чтобы оглянуться назад: что было на экране и что находилось в интерфейсе.

Связь с Telegram

Агент может писать вам в Telegram и читать ваши ответы — даже если вы сейчас не в чате с ним.

# один раз: привязать бота (токен от @BotFather и ваш chat id)
arena-bridge telegram setup --token 123456:AA... --chat-id 190771108

# проверить связь
arena-bridge telegram test

# посмотреть, что вам писали
arena-bridge telegram inbox

Что это даёт:

• notify_user — агент пишет вам: «сделал», «нужно ваше решение», «вот результат». С {"wait_for_reply": true} вызов ждёт вашего ответа прямо в Telegram.
• telegram_inbox — агент читает то, что вы написали боту: ответы, правки, поручения.
• telegram_status — бот, список чатов, число непрочитанных сообщений.
• Подтверждения из Telegram. Когда агенту нужно ваше «да», мост сам пишет вам: /approve <id> — разрешить, /deny <id> — отказать. Из терминала тоже можно: arena-bridge approve <id>.

Как это устроено и что защищено:

• токен бота лежит только в ~/.arena-bridge/config.json (права 0600); агент этот файл прочитать не может — он в списке защищённых путей;
• писать можно только в те чаты, что перечислены в --chat-id (по умолчанию — ваш);
• не больше 20 сообщений в минуту, одно сообщение — до 4000 символов;
• входящие сообщения мост слушает сам (служба launchd — автоматически), входящие лежат в ~/.arena-bridge/telegram/.

Одно уточнение: для бота api_id/api_hash не нужны — они пригодятся только для режима «личного аккаунта» (MTProto), который пока не включён.

Нативное приложение для macOS

Окно, в котором всё видно и всё управляется: статус, пуск/стоп, подтверждения, журнал.

git clone https://github.com/vernikr/arena-bridge.git
cd arena-bridge/macos/ArenaBridge
./build.sh                                   # → dist/Arena Bridge.app
cp -R "dist/Arena Bridge.app" /Applications/

Нужен только Swift из Xcode Command Line Tools (xcode-select --install), Xcode целиком не требуется. Собирается под текущую архитектуру: ARCH=x86_64 для Intel, ARCH=arm64 для Apple Silicon. Готовые сборки для обеих архитектур появляются в каждом выпуске на GitHub (см. «Быстрый старт»), собирать самому не нужно.

Окно следит за машиной само: статус, подтверждения и доверенное окно обновляются каждые несколько секунд, журнал — чуть реже. Кнопка обновления (⌘R) есть на всякий случай.

Когда агенту нужно решение, приложение показывает системное уведомление macOS «Approval needed» — в строке меню и в центре уведомлений. Внутри окна запрос тоже виден сразу, в карточке «Подтверждения».

«Настроить…» собирает конфиг, службу и запуск одной кнопкой: туннель (ngrok/cloudflared), зарезервированный домен, authtoken, папки для агента, Telegram (токен бота и chat id).

Иконка приложения лежит в macos/ArenaBridge/Resources/AppIcon.png; build.sh сам собирает из неё .icns и кладёт в бандл.

Подтверждения в Telegram: кнопки

Под сообщением «Approval needed» появляются нативные кнопки:

Approve once      Approve for 3h      Deny

• Approve once — разрешить этот запрос и всё;
• Approve for 3h — разрешить и открыть доверенное окно на 3 часа для этого же инструмента (команды больше не спрашивают);
• Deny — отклонить.

Кнопки работают и в приложении на Mac, и в Telegram; сообщение в Telegram после нажатия переписывается на итог. Прежние команды /approve <id> и /deny <id> тоже работают.

Доверенное окно: работать без подтверждений

arena-bridge trust --for 2h                                   # всё, на 2 часа
arena-bridge trust --for 30m --tools bash                     # только команды
arena-bridge trust --for 1h --paths ~/projects/my-app         # только эта папка
arena-bridge trust --status
arena-bridge trust --status --json                            # для приложений и скриптов
arena-bridge trust --off

• окно снимает требование подтверждения, но не снимает политику путей: за пределами roots и в защищённых каталогах по-прежнему PROTECTED;
• --paths ограничивает доверие конкретными папками; bash под такое ограничение не попадает — чтобы доверять командам, укажите --tools bash явно;
• окно живёт локально (~/.arena-bridge/trust.json), агент открыть его не может;
• после истечения срока подтверждения возвращаются сами, а все действия остаются в журнале.

Отдельные браузерные «кабинеты» агента

Агенту можно выдать несколько независимых профилей браузера — например «рабочий», «клиентский», «тестовый». В каждом свои входы, и они переживают перезапуск моста.

arena-bridge browser open work       # открыть Chrome с профилем «work»
# вы логинитесь в нужные сайты и закрываете окно — входы сохраняются
arena-bridge browser list             # какие профили есть
arena-bridge browser close work       # закрыть окно этого профиля

Агент открывает тот же профиль через chrome_launch {"profile":"work"} — уже с вашими входами. Каталог профилей агент тоже видит: chrome_profiles.

Ваш собственный Chrome (на порту 9222, с вашими сессиями) доступен отдельно — через chrome_attach; любые действия в нём требуют подтверждения.

Как это не мешает вам

Рекомендация для ноутбука с 16 ГБ и Intel 2019: отдельные профили браузера + фоновый режим + при необходимости второй рабочий стол macOS. Полноценная виртуальная машина того не стоит.

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

• Агент не может одобрить сам себя: POST /approvals/:id требует локальный токен.
• Пути ограничены: всё вне roots — PROTECTED. Защищённый список по умолчанию включает ~/.ssh, ~/.aws, ~/.arena-bridge, ~/.npmrc, профили браузеров, ключи.
• Подтверждения: bash, запись, удаление, управление вашим Chrome и десктопом ждут arena-bridge approve <id>. Ответ APPROVAL_PENDING содержит approval_id — покажите его пользователю и повторите вызов один раз.
• Журнал: ~/.arena-bridge/audit.log (JSONL) — кто, что и когда вызвал.
• Транспорт: сервер слушает 127.0.0.1, наружу — только туннель с HTTPS.

arena-bridge rotate            # новый агентский токен (действует мгновенно)
arena-bridge rotate --device   # новый девайсный токен
arena-bridge audit -n 50       # что происходило

Команды

API и MCP

GET  /health          liveness (без авторизации)
GET  /tools           каталог инструментов с JSON-схемами
GET  /prompt          этот промпт для агента
GET  /approvals       ожидающие подтверждения
GET  /audit           журнал работы с артефактами
GET  /audit/artifact  сохранённый артефакт (entry=, file=)
POST /call            {"tool":"bash","args":{...}}
POST /exec            {"command":"...","cwd":"...","timeout_sec":120}
GET|PUT|DELETE /files?path=/abs/path
POST /approvals/:id   {"decision":"approve"|"deny"}   — только по локальному токену
POST /mcp             MCP Streamable HTTP (protocolVersion 2025-06-18)

curl -sS -X POST "https://<ваш-url>/call" \
  -H "Authorization: Bearer $ARENA_BRIDGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tool":"sysinfo","args":{}}'

Разработка

npm install          # зависимостей нет — только dev-тесты
npm test             # 52 теста Node: direct, approval, trust, MCP, hub, туннель, Chrome, десктоп
npm run test:python  # 44 теста Python: то же самое

Тесты не требуют ни Chrome, ни Peekaboo: используются фейковые CDP- и Peekaboo-серверы (test/fake-cdp.mjs, test/fake-peekaboo.sh).

src/            Node-реализация (zero dependencies)
  ws.mjs        минимальный WebSocket-клиент
  cdp.mjs       клиент Chrome DevTools Protocol
  browser.mjs   13 инструментов chrome_*
  mac.mjs       20 инструментов mac_* (Peekaboo, Accessibility API)
  trust.mjs     окно доверия
  policy.mjs    проверка путей (roots / protected)
  engine.mjs    каталог, гейт подтверждений, аудит
  direct.mjs    HTTP-сервер
  hub.mjs       хаб для нескольких машин
  cli.mjs       команды
arena_bridge/  тот же функционал на Python (stdlib only)

Частые проблемы

Лицензия

MIT