Local Bridge — Setup-Anleitung

Verbinde deine lokale Maschine mit Arc OS in unter 90 Sekunden. Worker in der Cloud lesen/bearbeiten Dateien auf deinem Computer über eine einzelne Binary — kein Docker, kein Bun, keine Compiler-Toolchain.

Phase 23.2 · Zuletzt aktualisiert: 2026-05-14 · Getestet auf macOS 14+, Ubuntu 22+, Windows 11

Wähle dein OS — direkt zu den Schritten springen

Deine Maschine	Diese Anleitung öffnen
macOS (Apple Silicon oder Intel)	Local Bridge — macOS Setup
Linux (x64 oder arm64)	Local Bridge — Linux Setup
Windows 10 / 11	Local Bridge — Windows Setup

Der Rest dieser Seite behandelt plattformübergreifende Themen: Vorab-Checkliste, was die Bridge tatsächlich tut, häufige Fehler, Sicherheitsmodell und Diagnose. Lies es einmal durch; komm zurück, wenn etwas nicht funktioniert.

▶ 90-Sekunden-Walkthrough ansehen

🎬 Video-Platzhalter — Loom-Embed wird hier eingefügt, sobald es aufgezeichnet ist. Dateiname: bridge-walkthrough-2026-05.mp4 · 90s · CEO-Narration · Untertitel auf EN. Track: siehe Media-Shotlist §1.

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

Was du am Ende haben wirst

Zwei Fenster nebeneinander, beide mit „verbunden":

🖼️ Screenshot-Platzhalter — media/bridge/success-state.png Shot-Spec: Splitscreen — links = Terminal mit ✓ Connected to ws://… as <project>, rechts = CRM Bridge Setup-Seite mit grünem Punkt und Online neben deinem Maschinennamen.

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

Vorab-Checkliste

Bevor du anfängst, besorge dir diese Angaben aus dem CRM:

🖼️ Screenshot-Platzhalter — media/bridge/where-to-find-token.png Shot-Spec: CRM Einstellungen → Integrationen-Seite mit dem „Kopieren"-Button, der durch einen roten Pfeil + Kreis hervorgehoben ist. Token-Feld teilweise geschwärzt (nur eyJhbG...***...xyz sichtbar).

Schritt 0 — Was du herunterlädst

Die Local Bridge ist eine einzelne Binary-Datei, die du auf deinem Computer ausführst. Kein Installations-Wizard, kein Systemdienst, keine Admin-Rechte erforderlich. Du lädst eine Datei herunter, doppelklickst darauf (oder startest sie im Terminal), und sie läuft.

Verschiedene OS = verschiedene Binary. Deshalb zeigt dir die Bridge Setup-Seite im CRM 4 Buttons — jeder lädt eine andere Datei herunter, die für das jeweilige OS + CPU-Architektur kompiliert wurde. Wählst du die falsche, wird dein Computer sie ablehnen (Exec format error auf Linux, damaged auf macOS, not a valid Win32 application auf Windows).

🖼️ Screenshot-Platzhalter — media/bridge/bridge-setup-page-4-buttons.png Shot-Spec: CRM Einstellungen → Integrationen → Bridge Setup-Seite mit 4 Download-Buttons in einer Reihe: 🍎 macOS (Apple Silicon), 🍏 macOS (Intel), 🐧 Linux (x64), 🪟 Windows (x64). Token-Feld oben mit Kopieren-Button. 1280×720, Light Mode. Beschriftung: roter Kreis um den 🍎-Button als Beispiel.

Download-Größe & Dateitabelle

Dein Computer	Diesen Button klicken	Diese Datei erhalten	Größe
Mac mit Apple Silicon (M1/M2/M3/M4/M5)	macOS (Apple Silicon)	bridge-darwin-arm64.tar.gz	~50 MB
Älterer Mac (Intel, vor 2020)	macOS (Intel)	bridge-darwin-x64.tar.gz	~50 MB
Linux-Laptop / VM / Server	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

Warum Archive (.tar.gz) auf macOS/Linux, aber rohe .exe auf Windows? macOS versieht nicht-signierte heruntergeladene Binaries mit einer irreführenden „damaged"-Meldung. Das Archiv enthält die Binary + ein kleines install.command-Skript, das die Quarantäne für dich entfernt. Windows verwendet stattdessen SmartScreen — du klickst durch einen Dialog, kein Archiv nötig.

Plattform wählen — Entscheidungsbaum

flowchart TD
    Start[👤 CRM öffnen →<br/>Settings → Integrations →<br/>Bridge Setup] --> OS{Welches OS<br/>verwendest du?}
    OS -->|macOS| Mac[macOS-Anleitung<br/>öffnen]
    OS -->|Linux| Lin[Linux-Anleitung<br/>öffnen]
    OS -->|Windows| Win[Windows-Anleitung<br/>öffnen]

    Mac --> Connect[Token einfügen →<br/>Projektname → Enter]
    Lin --> Connect
    Win --> Connect
    Connect --> Done([✅ Verbunden])

Chip deines Macs unbekannt? Klicke auf das 🍎-Logo oben links → Über diesen Mac → suche nach „Chip: Apple M1/M2/M3/M4/M5" (Apple Silicon) oder „Prozessor: Intel Core …" (Intel). Im Zweifelsfall: Apple Silicon — jeder Mac seit November 2020.

Nach dem Start

🖼️ Screenshot-Platzhalter — media/bridge/crm-bridge-list.png Shot-Spec: CRM Bridge Setup-Seite zeigt deine Maschine in der Liste der verbundenen Geräte — grüner Punkt, Hostname, Projekt, „zuletzt gesehen: gerade eben", Laufzeit-Zähler der Sitzung.

Halte das Terminal-/PowerShell-Fenster offen — schließt du es, stoppt die Bridge.

Jede OS-spezifische Anleitung zeigt, wie du die Bridge im Hintergrund ausführst (nohup auf Unix, Start-Process -WindowStyle Hidden auf Windows). Ein dauerhafter Service-Modus (launchd / systemd / Windows Service) steht auf der Roadmap — siehe Phase 23.4.

Häufige Fehler — visuelle Referenz

🖼️ Screenshot-Platzhalter — media/bridge/error-gallery.png Shot-Spec: 4-Quadranten-Komposit: oben links = macOS damaged-Dialog, oben rechts = install.command-Verify-Dialog, unten links = Windows SmartScreen blau, unten rechts = Terminal mit ✗ Token expired. Jedes mit dem Fehler aus der obigen Tabelle beschriftet.

Was die Bridge tatsächlich tut

Die Bridge verbindet deine lokale Maschine mit dem Arc OS WebSocket-Relay. CRM-Worker können dann 5 sandboxed Tools aufrufen, um auf deine Dateien zuzugreifen:

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.

Alle Dateipfade sind sandboxed auf das Verzeichnis, in dem du die Bridge gestartet hast. Worker können daraus nicht über ../ entkommen.

Sicherheitsmodell

Erweitert — Flags und Umgebungsvariablen

Für CI-Skripte oder umgebungsgesteuerte Workflows:

# 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>

Diagnose

Steckst du fest? Führe diese Schritte der Reihe nach aus:

# 1. Ist die VPS erreichbar?
curl -s http://62.171.128.248:18888/api/master/health
# Erwartet: {"status":"ok","children":N,...}

# 2. Ist deine Bridge registriert? (<token> ersetzen)
curl -s -H "Authorization: Bearer <token>" \
  http://62.171.128.248:18888/api/internal/bridges
# Erwartet: JSON-Liste mit deinem Hostnamen

Wenn beides erfolgreich ist, die Bridge sich aber weiterhin neu verbindet → das Problem liegt zwischen Bridge und Relay (Firewall, VPN, Unternehmens-Proxy). WebSocket direkt testen:

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

Aus dem Quellcode bauen (für Entwickler)

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

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

Die Ausgaben landen in dist/bridge-{platform} und werden als die auf der Bridge Setup-Seite bereitgestellten Binaries ins CRM hochgeladen.

Referenz

• API: /api/internal/bridges — verbundene Bridges auflisten
• Architektur: Phase 23 — Local Gateway
• Quellcode: clients/bridge/ im GitHub-Repository
• OS-spezifische Anleitungen: macOS · Linux · Windows

Gepflegt vom Arc OS Team. Wenn du an einer Stelle nicht weitergekommen bist, die diese Anleitung nicht abdeckt, ist das ein Bug — schreib dem CEO eine DM oder poste in @arcos_beta_feedback.