Local Bridge — Guide d'installation

Connecte ta machine locale à Arc OS en moins de 90 secondes. Les workers dans le cloud lisent/éditent les fichiers de ton ordinateur via un seul binaire — pas de Docker, pas de Bun, pas de toolchain de compilation.

Phase 23.2 · Dernière mise à jour : 2026-05-14 · Testé sur macOS 14+, Ubuntu 22+, Windows 11

✅ Nouvelle méthode (#609) : le Bridge fait désormais partie du arc CLI

Tu ne télécharges plus un bridge-*.exe séparé et ne colles plus de token. Le Bridge est une commande du arc CLI — un binaire, un login, auto-mise à jour :

# 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 réutilise ta session arc login, se souvient du dernier projet (donc un simple arc bridge le reprend), et migre automatiquement toute ancienne config bridge ~/.citadel. Appuie sur Ctrl+C pour arrêter.

Nécessite un plan Cloud actif. Le Bridge est une fonctionnalité du plan Cloud — il ne se connectera pas en Free/BYOK (arc bridge requires an active Cloud plan) et s'arrête en ~60s si ton plan expire. Gère ton plan sous Billing à arc-os.co/billing.

Les téléchargements autonomes bridge-*.exe et le flow de collage de token ci-dessous sont dépréciés et conservés uniquement pour les installs existants pendant la transition.

Choisis ton OS — saute directement aux étapes

Ta machine	Ouvre ce guide
macOS (Apple Silicon ou Intel)	Local Bridge — Installation macOS
Linux (x64 ou arm64)	Local Bridge — Installation Linux
Windows 10 / 11	Local Bridge — Installation Windows

Le reste de cette page couvre ce qui est commun à toutes les plateformes : checklist pré-vol, ce que fait réellement le bridge, erreurs courantes, modèle de sécurité et diagnostics. Lis-la une fois ; reviens quand quelque chose casse.

▶ Regarde la démo de 90 secondes

🎬 Emplacement vidéo — l'embed Loom vivra ici une fois enregistré. Nom de fichier : bridge-walkthrough-2026-05.mp4 · 90s · narration CEO · sous-titres en EN. Track : voir media shotlist §1.

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

Ce que tu auras à la fin

Deux fenêtres côte à côte, toutes les deux indiquant « connected » :

🖼️ Emplacement capture d'écran — media/bridge/success-state.png Spec de la prise : écran divisé — gauche = Terminal affichant ✓ Connected to ws://… as <project>, droite = page Bridge Setup du CRM avec un point vert et Online à côté du nom de ta machine.

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

Checklist pré-vol

Avant de commencer, récupère ceci dans le CRM :

🖼️ Emplacement capture d'écran — media/bridge/where-to-find-token.png Spec de la prise : page CRM Settings → Integrations avec le bouton « Copy » mis en évidence par une flèche rouge + cercle. Champ du token partiellement expurgé (montrer seulement eyJhbG...***...xyz).

Étape 0 — Ce que tu télécharges

Le Local Bridge est un fichier binaire unique que tu exécutes sur ton ordinateur. Pas d'assistant d'installation, pas de service système, aucun droit admin nécessaire. Tu télécharges un fichier, double-cliques (ou lances depuis le terminal), et il tourne.

OS différent = binaire différent. C'est pourquoi la page Bridge Setup du CRM te montre 4 boutons — chacun télécharge un fichier différent compilé pour cet OS + cette architecture CPU. Choisis le mauvais et ton ordinateur refusera de l'exécuter (Exec format error sur Linux, damaged sur macOS, not a valid Win32 application sur Windows).

🖼️ Emplacement capture d'écran — media/bridge/bridge-setup-page-4-buttons.png Spec de la prise : page CRM Settings → Integrations → Bridge Setup montrant 4 boutons de téléchargement en ligne : 🍎 macOS (Apple Silicon), 🍏 macOS (Intel), 🐧 Linux (x64), 🪟 Windows (x64). Champ du token au-dessus avec bouton Copy. 1280×720, mode clair. Annotation : cercle rouge autour du bouton 🍎 que l'utilisateur d'exemple choisit.

Taille de téléchargement & table des fichiers

Ton ordinateur	Clique sur ce bouton	Obtiens ce fichier	Taille
Mac avec Apple Silicon (M1/M2/M3/M4/M5)	macOS (Apple Silicon)	bridge-darwin-arm64.tar.gz	~50 Mo
Mac plus ancien (Intel, avant 2020)	macOS (Intel)	bridge-darwin-x64.tar.gz	~50 Mo
Laptop / VM / serveur Linux	Linux (x64)	bridge-linux-x64.tar.gz	~50 Mo
Linux ARM (Raspberry Pi, AWS Graviton)	Linux (arm64)	bridge-linux-arm64.tar.gz	~50 Mo
PC Windows 10/11	Windows (x64)	bridge-windows-x64.exe	~55 Mo

Pourquoi des archives (.tar.gz) sur macOS/Linux mais un .exe brut sur Windows ? macOS met en quarantaine les binaires téléchargés non signés avec une erreur trompeuse « damaged ». L'archive regroupe le binaire + un petit script install.command qui retire la quarantaine pour toi. Windows utilise SmartScreen à la place — tu cliques à travers un seul dialogue, pas besoin d'archive.

Choisis ta plateforme — arbre de décision

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

Tu ne connais pas la puce de ton Mac ? Clique sur le logo 🍎 en haut à gauche → À propos de ce Mac → cherche « Puce : Apple M1/M2/M3/M4/M5 » (Apple Silicon) ou « Processeur : Intel Core … » (Intel). En cas de doute : Apple Silicon — tous les Mac vendus depuis novembre 2020.

Une fois en marche

🖼️ Emplacement capture d'écran — media/bridge/crm-bridge-list.png Spec de la prise : page CRM Bridge Setup montrant ta machine dans la liste des connectés — point vert, hostname, projet, « last seen: just now », compteur d'uptime de session.

Garde la fenêtre Terminal/PowerShell ouverte — la fermer arrête le bridge.

Chaque guide spécifique à l'OS montre comment lancer le bridge en arrière-plan (nohup sur Unix, Start-Process -WindowStyle Hidden sur Windows). Un mode service persistant (launchd / systemd / Windows Service) est sur la roadmap — voir la Phase 23.4.

Erreurs courantes — référence visuelle

🖼️ Emplacement capture d'écran — media/bridge/error-gallery.png Spec de la prise : composite en 4 quadrants : haut-gauche = dialogue macOS damaged, haut-droite = dialogue de vérification install.command, bas-gauche = SmartScreen bleu Windows, bas-droite = Terminal affichant ✗ Token expired. Chacun étiqueté avec l'erreur de la table ci-dessus.

Ce que fait réellement le Bridge

Le bridge connecte ta machine locale au relais WebSocket d'Arc OS. Les workers du CRM peuvent alors appeler 5 outils sandboxés pour accéder à tes fichiers :

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.

Tous les chemins de fichiers sont sandboxés vers le répertoire où tu as lancé le bridge. Les workers ne peuvent pas s'en échapper via ../.

Modèle de sécurité

Avancé — flags et environnement

Pour les scripts CI ou les workflows pilotés par 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>

Diagnostics

Bloqué ? Lance ceci dans l'ordre :

# 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

Si les deux réussissent mais que le bridge continue de se reconnecter → le problème est entre le bridge et le relais (firewall, VPN, proxy d'entreprise). Teste le WebSocket directement :

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

Build depuis les sources (développeurs)

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

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

Les sorties atterrissent dans dist/bridge-{platform} et sont uploadées vers le CRM comme les binaires servis sur la page Bridge Setup.

Référence

• API : /api/internal/bridges — lister les bridges connectés
• Architecture : Phase 23 — Local Gateway
• Source : clients/bridge/ dans le repo GitHub
• Guides spécifiques à l'OS : macOS · Linux · Windows

Maintenu par l'équipe Arc OS. Si tu es resté bloqué là où ce guide ne t'a pas aidé, c'est un bug — envoie un DM au CEO ou poste dans @arcos_beta_feedback.