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-embed з'явиться тут після запису. Файл: bridge-walkthrough-2026-05.mp4 · 90 секунд · озвучка CEO · субтитри EN. Трек: див. media shotlist §1.

┌──────────────────────────────────────────┐
│   ▶ Loom: Bridge Setup за 90 секунд      │
│         (заглушка до запису)             │
└──────────────────────────────────────────┘

Що ти отримаєш у підсумку

Два вікна поряд, обидва з написом "connected":

🖼️ Місце для скриншоту — media/bridge/success-state.png Специфікація кадру: розділений екран — ліворуч Terminal із ✓ 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 кнопки — кожна завантажує файл, скомпільований під відповідну ОС + CPU. Вибереш не той — твій комп'ютер відмовиться запускати (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{Яка в тебе<br/>ОС?}
    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([✅ Підключено])

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

Після того, як bridge запущений

🖼️ Місце для скриншоту — media/bridge/crm-bridge-list.png Специфікація кадру: сторінка CRM Bridge Setup, де у списку підключених видно твою машину — зелена крапка, hostname, проєкт, "last seen: just now", лічильник часу сесії.

Залишай вікно Terminal/PowerShell відкритим — якщо закриєш, bridge зупиниться.

У кожному гайді для конкретної ОС показано, як запустити bridge у фоні (nohup на Unix, Start-Process -WindowStyle Hidden на Windows). Постійний сервіс-режим (launchd / systemd / Windows Service) у дорожній карті — див. Phase 23.4.

Поширені помилки — візуальний довідник

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

Що насправді робить Bridge

Bridge підключає твою локальну машину до WebSocket-релею Arc OS. Воркери в CRM можуть викликати 5 пісочних інструментів для доступу до твоїх файлів:

sequenceDiagram
    participant W as Worker (cloud)
    participant R as Relay (VPS WS)
    participant B as Bridge (your laptop)
    participant FS as Local FS

    W->>R: read_file("./src/index.ts")
    R->>B: tool call
    B->>B: validate path (sandbox)
    B->>FS: read file
    FS-->>B: contents
    B-->>R: response
    R-->>W: contents
    Note over W,FS: Усі 5 інструментів проходять через цей цикл.<br/>execute_command спочатку показує жовтий банер.

Усі файлові шляхи в пісочниці обмежені директорією, з якої ти запустив bridge. Воркери не вийдуть з неї через ../.

Модель безпеки

Просунуто — прапори та змінні середовища

Для CI-скриптів або робочих процесів через env:

# Linux / macOS — env var
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-список із твоїм hostname

Якщо обидва успішні, але bridge постійно перепідключається → проблема між bridge і релеєм (firewall, 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 в DM або у @arcos_beta_feedback.