Local Bridge — посібник з налаштування

Підключи свою локальну машину до Arc OS менш ніж за 90 секунд. Воркери у хмарі читають/редагують файли на твоєму комп'ютері через єдиний бінарник — без Docker, без Bun, без набору інструментів компілятора.

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

✅ Новий спосіб (#609): Bridge тепер є частиною arc CLI

Тобі більше не треба завантажувати окремий bridge-*.exe чи вставляти токен. Bridge — це команда arc CLI — один бінарник, один вхід, авто-оновлення:

# 1. Install the arc CLI (see the CLI install guide for macOS/Linux/Windows)
#    Windows:  iwr https://arc-os.co/install.ps1 -useb | iex
#    macOS/Linux:  curl -sSf https://arc-os.co/install.sh | bash

# 2. Log in once (device-code flow, no token pasting)
arc login

# 3. Start the Bridge for a project (run it from the folder to sync into)
arc bridge <project>       # <project> = the name as it appears in your sidebar

arc bridge перевикористовує твою сесію arc login, запам'ятовує останній проєкт (тож голий arc bridge відновлює його) і автоматично мігрує будь-який старий конфіг Bridge із ~/.citadel. Натисни Ctrl+C, щоб зупинити.

Потребує активного плану Cloud. Bridge — це фіча плану Cloud — вона не під'єднається на Free/BYOK (arc bridge requires an active Cloud plan) і зупиняється протягом ~60с, якщо твій план завершився. Керуй планом у розділі Billing на arc-os.co/billing.

Завантаження окремого bridge-*.exe і потік вставки токена нижче застарілі й збережені лише для наявних інсталяцій під час перехідного періоду.

Обери свою ОС — переходь одразу до кроків

Твоя машина	Відкрий цей посібник
macOS (Apple Silicon або Intel)	Local Bridge — налаштування на macOS
Linux (x64 або arm64)	Local Bridge — налаштування на Linux
Windows 10 / 11	Local Bridge — налаштування на Windows

Решта цієї сторінки охоплює те, що спільне для всіх платформ: pre-flight чекліст, що саме робить bridge, поширені помилки, модель безпеки та діагностику. Прочитай це один раз; повертайся, коли щось зламається.

▶ Переглянь 90-секундний walkthrough

🎬 Заглушка для відео — тут буде Loom-embed після запису. Назва файлу: bridge-walkthrough-2026-05.mp4 · 90с · озвучка CEO · субтитри EN. Track: див. media shotlist §1.

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

Що ти отримаєш у кінці

Два вікна поруч, обидва кажуть "connected":

🖼️ Заглушка для скріншота — media/bridge/success-state.png Специфікація кадру: split screen — ліворуч = термінал показує ✓ 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 /     │
└─────────────────────────────────┘  └───────────────────────────────────┘

Pre-flight чекліст

Перед стартом збери це з 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 MB
Старіший Mac (Intel, до 2020)	macOS (Intel)	bridge-darwin-x64.tar.gz	~50 MB
Linux ноутбук / VM / сервер	Linux (x64)	bridge-linux-x64.tar.gz	~50 MB
Linux ARM (Raspberry Pi, AWS Graviton)	Linux (arm64)	bridge-linux-arm64.tar.gz	~50 MB
ПК на Windows 10/11	Windows (x64)	bridge-windows-x64.exe	~55 MB

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

Обери свою платформу — дерево рішень

flowchart TD
    Start[👤 Open CRM →<br/>Settings → Integrations →<br/>Bridge Setup] --> OS{Which OS<br/>are you on?}
    OS -->|macOS| Mac[Open<br/>macOS guide]
    OS -->|Linux| Lin[Open<br/>Linux guide]
    OS -->|Windows| Win[Open<br/>Windows guide]

    Mac --> Connect[Paste token →<br/>project name → 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 показує твою машину у списку підключених — зелена крапка, hostname, проєкт, "last seen: just now", лічильник uptime сесії.

Тримай вікно Terminal/PowerShell відкритим — його закриття зупиняє bridge.

Кожен OS-специфічний посібник показує, як запустити 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, унизу ліворуч = синій Windows SmartScreen, унизу праворуч = термінал показує ✗ Token expired. Кожен підписаний помилкою з таблиці вище.

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

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

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: All 5 tools follow the same loop.<br/>execute_command shows yellow banner first.

Усі шляхи до файлів у sandbox — обмежені текою, з якої ти запустив 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>

# Run from source (requires Bun ≥ 1.0)
CRM_TOKEN="eyJhbG..." bun scripts/bridge.ts --project <project>

Діагностика

Застряг? Запусти це по порядку:

# 1. Is the VPS reachable?
curl -s http://62.171.128.248:18888/api/master/health
# Expected: {"status":"ok","children":N,...}

# 2. Is your bridge registered? (replace <token>)
curl -s -H "Authorization: Bearer <token>" \
  http://62.171.128.248:18888/api/internal/bridges
# Expected: JSON list including your hostname

Якщо обидва успішні, але bridge усе одно переконнектиться → проблема між bridge і реле (firewall, VPN, корпоративний проксі). Протестуй WebSocket напряму:

# requires `wscat` — npm install -g wscat
wscat -c "ws://62.171.128.248:18888/ws/local-bridge?token=<token>"

Збірка з вихідного коду (для розробників)

# Single platform
bash scripts/build-bridge.sh linux

# All 4 platforms
bash scripts/build-bridge.sh

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

Довідка

• API: /api/internal/bridges — список підключених bridge
• Архітектура: Phase 23 — Local Gateway
• Вихідний код: clients/bridge/ у GitHub-репозиторії
• OS-специфічні посібники: macOS · Linux · Windows

Підтримується командою Arc OS. Якщо ти застряг там, де цей посібник не допоміг, — це баг; напиши CEO в DM або постни в @arcos_beta_feedback.