Local Bridge — Setup Guide

Connect your local machine to Arc OS in under 90 seconds. Workers in the cloud read/edit files on your computer through a single binary — no Docker, no Bun, no compiler toolchain.

Phase 23.2 · Last updated: 2026-05-14 · Tested on macOS 14+, Ubuntu 22+, Windows 11

Pick your OS — jump straight to the steps

Your machine	Open this guide
macOS (Apple Silicon or Intel)	Local Bridge — macOS Setup
Linux (x64 or arm64)	Local Bridge — Linux Setup
Windows 10 / 11	Local Bridge — Windows Setup

The rest of this page covers what's shared across platforms: pre-flight checklist, what the bridge actually does, common errors, security model and diagnostics. Read it once; come back when something breaks.

▶ Watch the 90-second walkthrough

🎬 Video placeholder — Loom embed will live here once recorded. Filename: bridge-walkthrough-2026-05.mp4 · 90s · CEO narration · captions in EN. Track: see media shotlist §1.

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

What you'll have at the end

Two windows side by side, both saying "connected":

🖼️ Screenshot placeholder — media/bridge/success-state.png Shot spec: split screen — left = Terminal showing ✓ Connected to ws://… as <project>, right = CRM Bridge Setup page with green dot and Online next to your machine name.

┌─ 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 checklist

Before you start, gather these from the CRM:

🖼️ Screenshot placeholder — media/bridge/where-to-find-token.png Shot spec: CRM Settings → Integrations page with the "Copy" button highlighted by a red arrow + circle. Token field partially redacted (show only eyJhbG...***...xyz).

Step 0 — What you're downloading

The Local Bridge is a single binary file you run on your computer. There's no installer wizard, no system service, no admin rights needed. You download one file, double-click (or run from terminal), and it's running.

Different OS = different binary. That's why the Bridge Setup page in CRM shows you 4 buttons — each downloads a different file compiled for that OS + CPU architecture. Pick the wrong one and your computer will refuse to run it (Exec format error on Linux, damaged on macOS, not a valid Win32 application on Windows).

🖼️ Screenshot placeholder — media/bridge/bridge-setup-page-4-buttons.png Shot spec: CRM Settings → Integrations → Bridge Setup page showing 4 download buttons in a row: 🍎 macOS (Apple Silicon), 🍏 macOS (Intel), 🐧 Linux (x64), 🪟 Windows (x64). Token field above with Copy button. 1280×720, light mode. Annotation: red circle around 🍎 button as the example user picks.

Download size & file table

Your computer	Click this button	Get this file	Size
Mac with Apple Silicon (M1/M2/M3/M4/M5)	macOS (Apple Silicon)	bridge-darwin-arm64.tar.gz	~50 MB
Older Mac (Intel, pre-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

Why archives (.tar.gz) on macOS/Linux but raw .exe on Windows? macOS quarantines unsigned downloaded binaries with a misleading "damaged" error. The archive bundles the binary + a tiny install.command script that strips the quarantine for you. Windows uses SmartScreen instead — you click through one dialog, no archive needed.

Pick your platform — decision tree

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])

Don't know your Mac's chip? Click 🍎 logo in top-left → About This Mac → look for "Chip: Apple M1/M2/M3/M4/M5" (Apple Silicon) or "Processor: Intel Core …" (Intel). When in doubt: Apple Silicon — every Mac sold since November 2020.

After it's running

🖼️ Screenshot placeholder — media/bridge/crm-bridge-list.png Shot spec: CRM Bridge Setup page showing your machine in the connected list — green dot, hostname, project, "last seen: just now", session uptime counter.

Keep the Terminal/PowerShell window open — closing it stops the bridge.

Each OS-specific guide shows how to run the bridge in the background (nohup on Unix, Start-Process -WindowStyle Hidden on Windows). A persistent service mode (launchd / systemd / Windows Service) is on the roadmap — see Phase 23.4.

Common errors — visual reference

🖼️ Screenshot placeholder — media/bridge/error-gallery.png Shot spec: 4-quadrant composite: top-left = macOS damaged dialog, top-right = install.command verify dialog, bottom-left = Windows SmartScreen blue, bottom-right = Terminal showing ✗ Token expired. Each labeled with the error from the table above.

What the Bridge actually does

The bridge connects your local machine to the Arc OS WebSocket relay. CRM workers can then call 5 sandboxed tools to access your files:

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.

All file paths are sandboxed to the directory where you launched the bridge. Workers can't escape it via ../.

Security model

Advanced — flags and environment

For CI scripts or env-driven 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>

Diagnostics

Stuck? Run these in order:

# 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

If both succeed but the bridge keeps reconnecting → the issue is between bridge and relay (firewall, VPN, corporate proxy). Test WebSocket directly:

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

Build from source (developers)

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

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

Outputs land in dist/bridge-{platform} and are uploaded to the CRM as the binaries served on the Bridge Setup page.

Reference

• API: /api/internal/bridges — list connected bridges
• Architecture: Phase 23 — Local Gateway
• Source: clients/bridge/ in the GitHub repo
• OS-specific guides: macOS · Linux · Windows

Maintained by Arc OS Team. If you got stuck where this guide didn't help, that's a bug — DM the CEO or post in @arcos_beta_feedback.