Arc OS Docs Open in app →

Local Bridge — Guide d'installation

Connecte ta machine locale à Arc OS en moins de 90 secondes. Les workers dans le cloud lisent et modifient les fichiers de ton ordinateur via un seul binaire — sans Docker, sans Bun, sans chaîne de compilation.

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

Choisis ton OS — accède directement aux étapes

Ta machine Ouvrir 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 de pré-vol, ce que le bridge fait réellement, erreurs courantes, modèle de sécurité et diagnostics. Lis-le une fois ; reviens quand quelque chose ne fonctionne pas.

▶ Regarde le walkthrough de 90 secondes

🎬 Vidéo à venir — L'intégration Loom sera ici une fois enregistrée. Nom du fichier : bridge-walkthrough-2026-05.mp4 · 90s · narration CEO · sous-titres EN. Suivi : voir liste de médias §1.

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

Ce que tu auras à la fin

Deux fenêtres côte à côte, toutes deux indiquant "connecté" :

🖼️ Capture d'écran à venir — media/bridge/success-state.png Spec : écran partagé — gauche = Terminal affichant ✓ Connected to ws://… as <project>, droite = CRM page Bridge Setup 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 de pré-vol

Avant de commencer, récupère ces éléments dans le CRM :

Élément Où le trouver Format
Token Paramètres → Intégrations → Bridge Setup → cliquer Copier eyJhbG… JWT, ~250 caractères, TTL 24h
Nom technique du projet Barre latérale → ton projet → slug URL (le nom en minuscules, pas le nom d'affichage) minuscules, tirets/underscores uniquement
Architecture de ton OS macOS : ⌘+Espace → "À propos de ce Mac" · Win : Paramètres → Système → À propos · Linux : uname -m arm64, x64, aarch64

🖼️ Capture d'écran à venir — media/bridge/where-to-find-token.png Spec : page CRM Paramètres → Intégrations avec le bouton "Copier" mis en évidence par une flèche rouge + cercle. Champ token partiellement masqué (afficher uniquement eyJhbG...***...xyz).

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

Le Local Bridge est un seul fichier binaire que tu exécutes sur ton ordinateur. Pas d'assistant d'installation, pas de service système, pas de droits administrateur nécessaires. Tu télécharges un fichier, double-cliques dessus (ou le lances depuis le terminal), et c'est parti.

OS différent = binaire différent. C'est pourquoi la page Bridge Setup dans le CRM affiche 4 boutons — chacun télécharge un fichier différent compilé pour cet OS + architecture CPU. Prends 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).

🖼️ Capture d'écran à venir — media/bridge/bridge-setup-page-4-buttons.png Spec : page CRM Paramètres → Intégrations → Bridge Setup affichant 4 boutons de téléchargement en ligne : 🍎 macOS (Apple Silicon), 🍏 macOS (Intel), 🐧 Linux (x64), 🪟 Windows (x64). Champ token au-dessus avec bouton Copier. 1280×720, mode clair. Annotation : cercle rouge autour du bouton 🍎 comme exemple.

Taille des téléchargements et tableau des fichiers

Ta machine Cliquer ce bouton Obtenir 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 Linux / VM / serveur 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 "damaged" trompeuse. L'archive regroupe le binaire + un petit script install.command qui supprime la quarantaine pour toi. Windows utilise SmartScreen à la place — tu cliques sur une boîte de dialogue, pas besoin d'archive.

Choisis ta plateforme — arbre de décision

flowchart TD
    Start[👤 Ouvrir le CRM →<br/>Paramètres → Intégrations →<br/>Bridge Setup] --> OS{Quel OS<br/>utilises-tu ?}
    OS -->|macOS| Mac[Ouvrir le<br/>guide macOS]
    OS -->|Linux| Lin[Ouvrir le<br/>guide Linux]
    OS -->|Windows| Win[Ouvrir le<br/>guide Windows]

    Mac --> Connect[Coller le token →<br/>nom du projet → Entrée]
    Lin --> Connect
    Win --> Connect
    Connect --> Done([✅ Connecté])

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 le bridge lancé

🖼️ Capture d'écran à venir — media/bridge/crm-bridge-list.png Spec : page CRM Bridge Setup affichant ta machine dans la liste des connexions — point vert, nom d'hôte, projet, "last seen: just now", compteur de durée de session.

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

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

Erreurs courantes — référence visuelle

Erreur Ce que tu vois Que faire
bridge-darwin-arm64 is damaged Boîte de dialogue macOS avec les boutons Corbeille/Annuler Cliquer Annuler, exécuter install.command à la place. Voir guide macOS
install.command can't be opened because Apple cannot check it for malicious software Boîte de dialogue macOS au premier lancement Clic droit sur install.command → Ouvrir → Ouvrir
Windows protected your PC Boîte de dialogue bleue SmartScreen Plus d'informations → Exécuter quand même. Voir guide Windows
Token is required / Invalid token Le bridge quitte avec une erreur rouge Token expiré (TTL 24h). Reconnecte-toi au CRM, copie un nouveau token
Project not found Le bridge quitte Utilise le nom technique (slug URL), pas le nom d'affichage
Le bridge se reconnecte sans cesse Reconnecting in 4s… 8s… 16s… Le VPS est peut-être en panne : curl http://62.171.128.248:18888/api/master/health
search_files retourne vide L'outil réussit mais aucun résultat Installe ripgrep pour une recherche de qualité ; sans lui, retombe sur une analyse native plus lente

🖼️ Capture d'écran à venir — media/bridge/error-gallery.png Spec : composite en 4 quadrants : haut-gauche = boîte de dialogue macOS "damaged", haut-droite = boîte de dialogue de vérification install.command, bas-gauche = SmartScreen Windows bleu, bas-droite = Terminal affichant ✗ Token expired. Chacun étiqueté avec l'erreur du tableau ci-dessus.

Ce que le Bridge fait réellement

Le bridge connecte ta machine locale au relais WebSocket d'Arc OS. Les workers 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 (ton 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: Les 5 outils suivent la même boucle.<br/>execute_command affiche d'abord une bannière jaune.
Outil Ce qu'il fait
read_file Lire le contenu d'un fichier
write_file Créer ou écraser un fichier
list_directory Lister les fichiers et dossiers avec leurs tailles
search_files Rechercher dans le contenu des fichiers (utilise ripgrep si disponible)
execute_command Exécuter une commande shell — affichée dans ton terminal avec une bannière jaune

Tous les chemins de fichiers sont sandboxés dans le répertoire depuis lequel tu as lancé le bridge. Les workers ne peuvent pas en sortir via ../.

Modèle de sécurité

Couche Protection
Authentification WebSocket nécessite un JWT valide (TTL 24h, HMAC-SHA256, comparaison timingSafeEqual côté serveur)
Sandboxing des chemins Toutes les opérations fichiers restreintes au répertoire de lancement ; safePath() rejette .., les chemins absolus, les échappements de liens symboliques
Liste blanche d'outils Seulement 5 outils autorisés ; client et serveur rejettent les noms d'outils inconnus
Visibilité des commandes execute_command affiche une bannière jaune dans ton terminal avant exécution — tu peux envoyer SIGINT pour annuler
Expiration du token TTL 24h — même en cas de fuite, la fenêtre d'exposition est limitée
Reconnexion automatique Coupure de connexion → backoff exponentiel 2s → 4s → 8s → … → plafond 30s

Avancé — flags et variables d'environnement

Pour les scripts CI ou les workflows pilotés par variables d'environnement :

# Linux / macOS — variable d'environnement
CRM_TOKEN="eyJhbG..." ./bridge-linux-x64 --project <project>

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

# Exécuter depuis les sources (nécessite Bun ≥ 1.0)
CRM_TOKEN="eyJhbG..." bun scripts/bridge.ts --project <project>
Flag Défaut Description
--project <name> (invite interactive) Nom du projet à lier
--server <url> ws://62.171.128.248:18888/ws/local-bridge URL du relais WebSocket
--help, -h — Afficher l'aide

Diagnostics

Bloqué ? Exécute ces commandes dans l'ordre :

# 1. Le VPS est-il accessible ?
curl -s http://62.171.128.248:18888/api/master/health
# Attendu : {"status":"ok","children":N,...}

# 2. Ton bridge est-il enregistré ? (remplacer <token>)
curl -s -H "Authorization: Bearer <token>" \
  http://62.171.128.248:18888/api/internal/bridges
# Attendu : liste JSON incluant ton nom d'hôte

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

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

Compiler depuis les sources (développeurs)

# Plateforme unique
bash scripts/build-bridge.sh linux

# Les 4 plateformes
bash scripts/build-bridge.sh

Les sorties se trouvent dans dist/bridge-{platform} et sont uploadées vers le CRM en tant que binaires servis sur la page Bridge Setup.

Référence

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