Local Bridge — Гайд по настройке

Подключи свою локальную машину к Arc OS менее чем за 90 секунд. Воркеры в облаке читают и редактируют файлы на твоём компьютере через один бинарник — без Docker, без Bun, без компилятора.

Phase 23.2 · Последнее обновление: 2026-05-14 · Протестировано на macOS 14+, Ubuntu 22+, Windows 11

Выбери ОС — переходи сразу к шагам

Твоя машина	Открой этот гайд
macOS (Apple Silicon или Intel)	Local Bridge — настройка macOS
Linux (x64 или arm64)	Local Bridge — настройка Linux
Windows 10 / 11	Local Bridge — настройка Windows

На этой странице — всё общее для всех платформ: чеклист перед стартом, что именно делает bridge, типичные ошибки, модель безопасности и диагностика. Прочитай один раз; возвращайся, когда что-то сломается.

▶ Посмотри 90-секундный обзор

🎬 Заглушка видео — Loom-эмбед появится здесь после записи. Имя файла: bridge-walkthrough-2026-05.mp4 · 90 сек · нарратив CEO · субтитры EN. Трек: см. медиа-шотлист §1.

┌──────────────────────────────────────────┐
│   ▶ Loom: Bridge Setup in 90 Seconds     │
│        (placeholder until recorded)      │
└──────────────────────────────────────────┘

Что будет в итоге

Два окна рядом, оба говорят «connected»:

🖼️ Заглушка скриншота — media/bridge/success-state.png Спецификация: разделённый экран — слева = Терминал с ✓ Connected to ws://… as <project>, справа = CRM-страница Bridge Setup с зелёной точкой и Online рядом с именем машины.

┌─ Terminal ─────────────────────┐  ┌─ Browser: arc-os.co ──────────────┐
│ $ bash install.sh               │  │  Bridge Setup                     │
│ ✓ Quarantine stripped           │  │  ●  <your-machine>     Online     │
│ ✓ Token validated               │  │  Last seen: just now              │
│ ✓ Connected                     │  │                                   │
│   Watching ~/projects/<project> │  │  Connected workers can read /     │
└─────────────────────────────────┘  └───────────────────────────────────┘

Чеклист перед стартом

Перед началом возьми из CRM:

🖼️ Заглушка скриншота — media/bridge/where-to-find-token.png Спецификация: страница CRM Settings → Integrations с выделенной кнопкой «Copy» (красная стрелка + круг). Поле токена частично скрыто (показывает только eyJhbG...***...xyz).

Шаг 0 — Что ты скачиваешь

Local Bridge — это один бинарный файл, который ты запускаешь на своём компьютере. Никакого мастера установки, никакой системной службы, никаких прав администратора. Скачиваешь один файл, двойной клик (или запуск из терминала) — и он уже работает.

Разная ОС = разный бинарник. Поэтому на странице Bridge Setup в CRM есть 4 кнопки — каждая скачивает отдельный файл, скомпилированный для конкретной ОС + архитектуры процессора. Выберешь не ту — компьютер откажется его запускать (Exec format error на Linux, damaged на macOS, not a valid Win32 application на Windows).

🖼️ Заглушка скриншота — media/bridge/bridge-setup-page-4-buttons.png Спецификация: страница CRM Settings → Integrations → Bridge Setup с 4 кнопками скачивания в ряд: 🍎 macOS (Apple Silicon), 🍏 macOS (Intel), 🐧 Linux (x64), 🪟 Windows (x64). Поле токена выше с кнопкой Copy. 1280×720, светлая тема. Аннотация: красный круг вокруг кнопки 🍎 как пример выбора.

Размер скачиваемого файла и таблица

Твой компьютер	Нажми эту кнопку	Получишь файл	Размер
Mac с Apple Silicon (M1/M2/M3/M4/M5)	macOS (Apple Silicon)	bridge-darwin-arm64.tar.gz	~50 МБ
Старый Mac (Intel, до 2020)	macOS (Intel)	bridge-darwin-x64.tar.gz	~50 МБ
Linux-ноутбук / VM / сервер	Linux (x64)	bridge-linux-x64.tar.gz	~50 МБ
Linux ARM (Raspberry Pi, AWS Graviton)	Linux (arm64)	bridge-linux-arm64.tar.gz	~50 МБ
Windows 10/11 ПК	Windows (x64)	bridge-windows-x64.exe	~55 МБ

Почему архивы (.tar.gz) на macOS/Linux, но сырой .exe на Windows? macOS помечает неподписанные скачанные бинарники карантином с вводящей в заблуждение ошибкой «damaged». Архив включает бинарник + небольшой скрипт install.command, который снимает карантин. Windows использует SmartScreen — там достаточно кликнуть один диалог, архив не нужен.

Выбери платформу — дерево решений

flowchart TD
    Start[👤 Открой CRM →<br/>Settings → Integrations →<br/>Bridge Setup] --> OS{Какая у тебя ОС?}
    OS -->|macOS| Mac[Открой<br/>гайд macOS]
    OS -->|Linux| Lin[Открой<br/>гайд Linux]
    OS -->|Windows| Win[Открой<br/>гайд Windows]

    Mac --> Connect[Вставь токен →<br/>имя проекта → Enter]
    Lin --> Connect
    Win --> Connect
    Connect --> Done([✅ Connected])

Не знаешь чип своего Mac? Кликни логотип 🍎 (верхний левый угол) → About This Mac → ищи «Chip: Apple M1/M2/M3/M4/M5» (Apple Silicon) или «Processor: Intel Core …» (Intel). Если не уверен — Apple Silicon: каждый Mac, проданный после ноября 2020 года.

После запуска

🖼️ Заглушка скриншота — media/bridge/crm-bridge-list.png Спецификация: страница CRM Bridge Setup с твоей машиной в списке подключённых — зелёная точка, имя хоста, проект, «last seen: just now», счётчик uptime сессии.

Держи окно Terminal/PowerShell открытым — закрытие останавливает bridge.

В каждом ОС-специфичном гайде показано, как запустить bridge в фоне (nohup на Unix, Start-Process -WindowStyle Hidden на Windows). Постоянный режим службы (launchd / systemd / Windows Service) запланирован в фазе 23.4.

Типичные ошибки — визуальный справочник

🖼️ Заглушка скриншота — media/bridge/error-gallery.png Спецификация: коллаж из 4 квадрантов: верхний левый = диалог damaged macOS, верхний правый = диалог верификации install.command, нижний левый = синий SmartScreen Windows, нижний правый = терминал с ✗ Token expired. Каждый подписан ошибкой из таблицы выше.

Что делает Bridge на самом деле

Bridge подключает твою локальную машину к WebSocket-релею Arc OS. Воркеры CRM могут затем вызывать 5 инструментов в песочнице для доступа к твоим файлам:

sequenceDiagram
    participant W as Воркер (облако)
    participant R as Релей (VPS WS)
    participant B as Bridge (твой ноутбук)
    participant FS as Локальная ФС

    W->>R: read_file("./src/index.ts")
    R->>B: вызов инструмента
    B->>B: валидация пути (песочница)
    B->>FS: чтение файла
    FS-->>B: содержимое
    B-->>R: ответ
    R-->>W: содержимое
    Note over W,FS: Все 5 инструментов работают по той же схеме.<br/>execute_command сначала показывает жёлтый баннер.

Все пути к файлам ограничены песочницей — директорией, из которой ты запустил bridge. Воркеры не могут выйти за её пределы через ../.

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

Дополнительно — флаги и окружение

Для CI-скриптов или воркфлоу через переменные окружения:

# Linux / macOS — переменная окружения
CRM_TOKEN="eyJhbG..." ./bridge-linux-x64 --project <project>

# Windows PowerShell
$env:CRM_TOKEN = "eyJhbG..."
.\bridge-windows-x64.exe --project <project>

# Запуск из исходников (требует Bun ≥ 1.0)
CRM_TOKEN="eyJhbG..." bun scripts/bridge.ts --project <project>

Диагностика

Застрял? Выполни по порядку:

# 1. Доступен ли VPS?
curl -s http://62.171.128.248:18888/api/master/health
# Ожидается: {"status":"ok","children":N,...}

# 2. Зарегистрирован ли твой bridge? (замени <token>)
curl -s -H "Authorization: Bearer <token>" \
  http://62.171.128.248:18888/api/internal/bridges
# Ожидается: JSON-список, включающий твоё имя хоста

Если оба запроса успешны, но bridge продолжает переподключаться → проблема между bridge и релеем (файрвол, VPN, корпоративный прокси). Протестируй WebSocket напрямую:

# требует `wscat` — npm install -g wscat
wscat -c "ws://62.171.128.248:18888/ws/local-bridge?token=<token>"

Сборка из исходников (для разработчиков)

# Одна платформа
bash scripts/build-bridge.sh linux

# Все 4 платформы
bash scripts/build-bridge.sh

Результаты попадают в dist/bridge-{platform} и загружаются в CRM как бинарники, которые отдаёт страница Bridge Setup.

Справочные материалы

• API: /api/internal/bridges — список подключённых bridge
• Архитектура: Phase 23 — Local Gateway
• Исходники: clients/bridge/ в GitHub-репозитории
• ОС-специфичные гайды: macOS · Linux · Windows

Поддерживается командой Arc OS. Если застрял там, где этот гайд не помог — это баг: напиши CEO в личку или публикуй в @arcos_beta_feedback.