Local Bridge — Przewodnik konfiguracji

Połącz swój lokalny komputer z Arc OS w mniej niż 90 sekund. Workerzy w chmurze czytają i edytują pliki na twoim komputerze przez jeden plik binarny — bez Dockera, bez Bun, bez łańcucha narzędzi kompilacji.

Phase 23.2 · Ostatnia aktualizacja: 2026-05-14 · Testowane na macOS 14+, Ubuntu 22+, Windows 11

Wybierz swój system — przejdź od razu do kroków

Twój komputer	Otwórz ten przewodnik
macOS (Apple Silicon lub Intel)	Local Bridge — Konfiguracja macOS
Linux (x64 lub arm64)	Local Bridge — Konfiguracja Linux
Windows 10 / 11	Local Bridge — Konfiguracja Windows

Reszta tej strony obejmuje to, co jest wspólne dla wszystkich platform: lista pre-flight, co bridge faktycznie robi, typowe błędy, model bezpieczeństwa i diagnostyka. Przeczytaj raz; wróć, gdy coś przestanie działać.

▶ Obejrzyj 90-sekundowy przewodnik

🎬 Miejsce na wideo — tu pojawi się embed Loom po nagraniu. Nazwa pliku: bridge-walkthrough-2026-05.mp4 · 90s · narracja CEO · napisy w EN. Śledzenie: zob. shotlist mediów §1.

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

Co będziesz mieć na końcu

Dwa okna obok siebie, oba ze statusem „connected":

🖼️ Miejsce na zrzut ekranu — media/bridge/success-state.png Specyfikacja zdjęcia: podzielony ekran — lewo = Terminal z ✓ Connected to ws://… as <project>, prawo = strona CRM Bridge Setup z zielonym punktem i Online obok nazwy twojego komputera.

┌─ 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 /     │
└─────────────────────────────────┘  └───────────────────────────────────┘

Lista pre-flight

Przed rozpoczęciem pobierz te dane z CRM:

🖼️ Miejsce na zrzut ekranu — media/bridge/where-to-find-token.png Specyfikacja zdjęcia: strona CRM Settings → Integrations z podświetlonym czerwoną strzałką + kółkiem przyciskiem „Copy". Pole tokena częściowo ukryte (pokaż tylko eyJhbG...***...xyz).

Krok 0 — Co pobierasz

Local Bridge to pojedynczy plik binarny, który uruchamiasz na swoim komputerze. Nie ma kreatora instalacji, usługi systemowej ani potrzeby uprawnień administratora. Pobierasz jeden plik, klikasz dwukrotnie (lub uruchamiasz z terminala) i działa.

Inny system = inny plik binarny. Dlatego strona Bridge Setup w CRM pokazuje 4 przyciski — każdy pobiera inny plik skompilowany dla tego systemu + architektury CPU. Wybór niewłaściwego spowoduje, że komputer odmówi uruchomienia (Exec format error na Linuksie, damaged na macOS, not a valid Win32 application na Windows).

🖼️ Miejsce na zrzut ekranu — media/bridge/bridge-setup-page-4-buttons.png Specyfikacja zdjęcia: strona CRM Settings → Integrations → Bridge Setup z 4 przyciskami pobierania w rzędzie: 🍎 macOS (Apple Silicon), 🍏 macOS (Intel), 🐧 Linux (x64), 🪟 Windows (x64). Pole tokena powyżej z przyciskiem Copy. 1280×720, tryb jasny. Adnotacja: czerwone kółko wokół przycisku 🍎 jako przykładowy wybór użytkownika.

Rozmiar pliku i tabela pobrań

Twój komputer	Kliknij ten przycisk	Pobierz ten plik	Rozmiar
Mac z Apple Silicon (M1/M2/M3/M4/M5)	macOS (Apple Silicon)	bridge-darwin-arm64.tar.gz	~50 MB
Starszy Mac (Intel, przed 2020)	macOS (Intel)	bridge-darwin-x64.tar.gz	~50 MB
Laptop Linux / VM / serwer	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 PC	Windows (x64)	bridge-windows-x64.exe	~55 MB

Dlaczego archiwa (.tar.gz) na macOS/Linux, ale surowy .exe na Windows? macOS poddaje kwarantannie niepodpisane pobrane pliki binarne z mylącym błędem „damaged". Archiwum zawiera plik binarny + mały skrypt install.command, który usuwa kwarantannę. Windows używa SmartScreen — klikasz przez jedno okno dialogowe, archiwum nie jest potrzebne.

Wybierz platformę — drzewo decyzyjne

flowchart TD
    Start[👤 Otwórz CRM →<br/>Settings → Integrations →<br/>Bridge Setup] --> OS{Jakiego systemu<br/>używasz?}
    OS -->|macOS| Mac[Otwórz<br/>przewodnik macOS]
    OS -->|Linux| Lin[Otwórz<br/>przewodnik Linux]
    OS -->|Windows| Win[Otwórz<br/>przewodnik Windows]

    Mac --> Connect[Wklej token →<br/>nazwa projektu → Enter]
    Lin --> Connect
    Win --> Connect
    Connect --> Done([✅ Connected])

Nie wiesz, jaki chip ma twój Mac? Kliknij logo 🍎 w lewym górnym rogu → About This Mac → szukaj „Chip: Apple M1/M2/M3/M4/M5" (Apple Silicon) lub „Processor: Intel Core …" (Intel). W razie wątpliwości: Apple Silicon — każdy Mac sprzedany od listopada 2020.

Po uruchomieniu

🖼️ Miejsce na zrzut ekranu — media/bridge/crm-bridge-list.png Specyfikacja zdjęcia: strona CRM Bridge Setup z twoim komputerem na liście połączonych — zielony punkt, hostname, projekt, „last seen: just now", licznik czasu sesji.

Trzymaj otwarte okno Terminala/PowerShell — zamknięcie go zatrzymuje bridge.

Każdy przewodnik dotyczący systemu pokazuje, jak uruchomić bridge w tle (nohup na Unix, Start-Process -WindowStyle Hidden na Windows). Tryb trwałej usługi (launchd / systemd / Windows Service) jest w roadmapie — zob. Phase 23.4.

Typowe błędy — wizualny przegląd

🖼️ Miejsce na zrzut ekranu — media/bridge/error-gallery.png Specyfikacja zdjęcia: kompozyt 4-kwadrantowy: lewy górny = dialog macOS damaged, prawy górny = dialog weryfikacji install.command, lewy dolny = niebieski ekran Windows SmartScreen, prawy dolny = Terminal z ✗ Token expired. Każdy podpisany błędem z tabeli powyżej.

Co bridge faktycznie robi

Bridge łączy twój lokalny komputer z przekaźnikiem WebSocket Arc OS. Workerzy CRM mogą wtedy wywoływać 5 narzędzi z piaskownicą do dostępu do twoich plików:

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.

Wszystkie ścieżki plików są izolowane do katalogu, z którego uruchomiono bridge. Workerzy nie mogą go opuścić przez ../.

Model bezpieczeństwa

Zaawansowane — flagi i środowisko

Dla skryptów CI lub przepływów sterowanych zmiennymi środowiskowymi:

# Linux / macOS — zmienna środowiskowa
CRM_TOKEN="eyJhbG..." ./bridge-linux-x64 --project <project>

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

# Uruchom ze źródła (wymaga Bun ≥ 1.0)
CRM_TOKEN="eyJhbG..." bun scripts/bridge.ts --project <project>

Diagnostyka

Utknąłeś? Uruchom te komendy kolejno:

# 1. Czy VPS jest osiągalny?
curl -s http://62.171.128.248:18888/api/master/health
# Oczekiwane: {"status":"ok","children":N,...}

# 2. Czy twój bridge jest zarejestrowany? (zastąp <token>)
curl -s -H "Authorization: Bearer <token>" \
  http://62.171.128.248:18888/api/internal/bridges
# Oczekiwane: lista JSON zawierająca twój hostname

Jeśli obie komendy się powiodą, ale bridge ciągle się łączy ponownie → problem jest między bridgem a przekaźnikiem (firewall, VPN, firmowe proxy). Przetestuj WebSocket bezpośrednio:

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

Kompilacja ze źródeł (dla deweloperów)

# Jedna platforma
bash scripts/build-bridge.sh linux

# Wszystkie 4 platformy
bash scripts/build-bridge.sh

Wyniki trafiają do dist/bridge-{platform} i są przesyłane do CRM jako pliki binarne serwowane na stronie Bridge Setup.

Odniesienia

• API: /api/internal/bridges — lista połączonych bridge'y
• Architektura: Phase 23 — Local Gateway
• Źródło: clients/bridge/ w repozytorium GitHub
• Przewodniki dla systemów: macOS · Linux · Windows

Utrzymywane przez Arc OS Team. Jeśli utknąłeś w miejscu, gdzie ten przewodnik nie pomógł, to błąd — napisz do CEO lub opublikuj w @arcos_beta_feedback.