Arc OS Docs Open in app →

Local Bridge — macOS Setup

macOS-specific install guide. For the general overview, pre-flight checklist, errors, security model and diagnostics, see Local Bridge — Setup Guide.

Total time: ~60 seconds assuming token already copied.

Pick your chip first

Your Mac Click this button in CRM Get this file
Apple Silicon (M1 / M2 / M3 / M4 / M5) macOS (Apple Silicon) bridge-darwin-arm64.tar.gz (~50 MB)
Intel (pre-2020 Mac) macOS (Intel) bridge-darwin-x64.tar.gz (~50 MB)

Not sure which chip you have? Click 🍎 logo (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.

The steps below are identical for both chips. Just substitute arm64 ↔ x64 in folder/binary names.

1. Download

In CRM: Settings → Integrations → Bridge Setup → 🍎 macOS (Apple Silicon) (or 🍏 for Intel).

Safari downloads bridge-darwin-arm64.tar.gz and auto-extracts it to ~/Downloads/bridge-darwin-arm64/.

🎞️ GIF placeholder — media/bridge/macos-download.gif Shot spec: 8-second screen recording — cursor clicks 🍎 button → Safari progress bar fills → folder appears in Finder.

The folder contains:

bridge-darwin-arm64/
├── bridge-darwin-arm64    ← the binary
├── install.sh             ← shell script (terminal-friendly)
└── install.command        ← Finder-friendly launcher

2. Run the installer

Easy way (Finder, no Terminal)

🎞️ GIF placeholder — media/bridge/macos-rightclick-open.gif Shot spec: 12-second recording — Finder open at ~/Downloads/bridge-darwin-arm64/, right-click install.command, choose Open from menu, "developer cannot be verified" dialog appears, click Open, Terminal launches with installer running.

  1. Open ~/Downloads/bridge-darwin-arm64/ in Finder
  2. Right-click install.command → Open
  3. Click Open in the "developer cannot be verified" dialog
  4. Terminal launches and runs the installer automatically

❗ Right-click → Open is mandatory on first launch. A normal double-click triggers Gatekeeper's hard-block. After the first successful run, double-click works forever.

Power-user way (Terminal)

cd ~/Downloads/bridge-darwin-arm64
bash install.sh

3. Connect

Before launching, grab two values from CRM:

What Where
Token Settings → Integrations → Bridge Setup → click Copy (JWT, 24h TTL)
Project technical name Sidebar → your project → URL slug (e.g. the lowercase one with hyphens, not the display name)

The bridge then prompts for three values:

Token (paste from CRM):  ⌘+V
Project name:             <project>
Server URL [enter for default]:  press ⏎

🖼️ Screenshot placeholder — media/bridge/macos-connected.png Shot spec: Terminal window post-connection. Visible lines: ✓ Token validated · ✓ Connected to ws://…/ws/local-bridge · Watching <abs-path>. Window title shows Terminal — install.command.

Q: Why a project name if I have several? One bridge instance binds to one project — the workers from that project read files only from the directory you launched the bridge in (sandboxed). To work with multiple projects, run one bridge per project in its own directory.

Q: Why a Server URL? Just press Enter. The default points to the Arc OS production relay. Custom URL is for self-hosted setups; you don't need to touch it.

If you see ✓ Connected, you're done. Switch to CRM → Bridge Setup and confirm the green dot.

❌ Three things to NOT do on macOS

🖼️ Screenshot placeholder — media/bridge/macos-damaged-error.png Shot spec: macOS dialog "bridge-darwin-arm64" is damaged and can't be opened. with Move to Trash / Cancel buttons. Annotation: red X over Move to Trash, green checkmark over Cancel.

Don't Why Do instead
Double-click bridge-darwin-arm64 directly Gatekeeper marks it "damaged" — confusing but expected for unsigned binaries Run install.command first; it strips the quarantine attribute
Click "Move to Trash" on the damaged dialog Loses your downloaded binary Click Cancel and use install.command
Drag the folder to Applications The bridge needs to run from where you launched it (sandbox root) Run it from ~/Downloads/bridge-darwin-arm64/ directly

Run in the background (daemonize)

nohup ./bridge-darwin-arm64 > bridge.log 2>&1 &

A persistent service mode (launchd) is on the roadmap — see Phase 23.4.

What's next