Local Bridge — Guía de configuración

Conecta tu máquina local a Arc OS en menos de 90 segundos. Los workers en la nube leen y editan archivos de tu ordenador a través de un único binario — sin Docker, sin Bun, sin cadena de compilación.

Phase 23.2 · Última actualización: 2026-05-14 · Probado en macOS 14+, Ubuntu 22+, Windows 11

Elige tu SO — ve directo a los pasos

Tu máquina	Abre esta guía
macOS (Apple Silicon o Intel)	Local Bridge — Configuración macOS
Linux (x64 o arm64)	Local Bridge — Configuración Linux
Windows 10 / 11	Local Bridge — Configuración Windows

El resto de esta página cubre lo que es común a todas las plataformas: lista de verificación previa, qué hace el bridge en realidad, errores frecuentes, modelo de seguridad y diagnósticos. Léelo una vez; vuelve cuando algo falle.

▶ Mira el tutorial de 90 segundos

🎬 Video placeholder — El embed de Loom estará aquí una vez grabado. Nombre de archivo: bridge-walkthrough-2026-05.mp4 · 90s · narración del CEO · subtítulos en EN. Track: ver lista de medios §1.

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

Qué tendrás al final

Dos ventanas en paralelo, ambas mostrando "connected":

🖼️ Screenshot placeholder — media/bridge/success-state.png Especificación: pantalla dividida — izquierda = Terminal mostrando ✓ Connected to ws://… as <project>, derecha = CRM página Bridge Setup con punto verde y Online junto al nombre de tu máquina.

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

Lista de verificación previa

Antes de empezar, reúne estos datos del CRM:

🖼️ Screenshot placeholder — media/bridge/where-to-find-token.png Especificación: página Settings → Integrations del CRM con el botón "Copy" resaltado con una flecha y círculo rojo. Campo del token parcialmente redactado (mostrar solo eyJhbG...***...xyz).

Paso 0 — Qué estás descargando

El Local Bridge es un único archivo binario que ejecutas en tu ordenador. No hay asistente de instalación, no hay servicio de sistema, no se necesitan permisos de administrador. Descargas un archivo, haces doble clic (o lo ejecutas desde la terminal), y ya está funcionando.

SO diferente = binario diferente. Por eso la página Bridge Setup del CRM muestra 4 botones — cada uno descarga un archivo diferente compilado para ese SO + arquitectura CPU. Si eliges el incorrecto, tu ordenador se negará a ejecutarlo (Exec format error en Linux, damaged en macOS, not a valid Win32 application en Windows).

🖼️ Screenshot placeholder — media/bridge/bridge-setup-page-4-buttons.png Especificación: página Settings → Integrations → Bridge Setup del CRM mostrando 4 botones de descarga en fila: 🍎 macOS (Apple Silicon), 🍏 macOS (Intel), 🐧 Linux (x64), 🪟 Windows (x64). Campo de token arriba con botón Copy. 1280×720, modo claro. Anotación: círculo rojo alrededor del botón 🍎 como ejemplo del usuario.

Tamaño de descarga y tabla de archivos

Tu ordenador	Haz clic en este botón	Obtienes este archivo	Tamaño
Mac con Apple Silicon (M1/M2/M3/M4/M5)	macOS (Apple Silicon)	bridge-darwin-arm64.tar.gz	~50 MB
Mac antiguo (Intel, anterior a 2020)	macOS (Intel)	bridge-darwin-x64.tar.gz	~50 MB
Laptop / VM / servidor Linux	Linux (x64)	bridge-linux-x64.tar.gz	~50 MB
Linux ARM (Raspberry Pi, AWS Graviton)	Linux (arm64)	bridge-linux-arm64.tar.gz	~50 MB
PC Windows 10/11	Windows (x64)	bridge-windows-x64.exe	~55 MB

¿Por qué archivos comprimidos (.tar.gz) en macOS/Linux pero .exe directo en Windows? macOS pone en cuarentena los binarios descargados sin firma con un confuso error de "damaged". El archivo incluye el binario + un pequeño script install.command que elimina la cuarentena por ti. Windows usa SmartScreen en su lugar — haces clic en un diálogo, sin archivo comprimido necesario.

Elige tu plataforma — árbol de decisión

flowchart TD
    Start[👤 Abre CRM →<br/>Settings → Integrations →<br/>Bridge Setup] --> OS{¿Qué SO<br/>usas?}
    OS -->|macOS| Mac[Abre la guía<br/>macOS]
    OS -->|Linux| Lin[Abre la guía<br/>Linux]
    OS -->|Windows| Win[Abre la guía<br/>Windows]

    Mac --> Connect[Pega el token →<br/>nombre del proyecto → Enter]
    Lin --> Connect
    Win --> Connect
    Connect --> Done([✅ Conectado])

¿No sabes qué chip tiene tu Mac? Haz clic en el logo 🍎 en la esquina superior izquierda → About This Mac → busca "Chip: Apple M1/M2/M3/M4/M5" (Apple Silicon) o "Processor: Intel Core …" (Intel). Si no estás seguro: Apple Silicon — todos los Mac vendidos desde noviembre de 2020.

Una vez que esté ejecutándose

🖼️ Screenshot placeholder — media/bridge/crm-bridge-list.png Especificación: página Bridge Setup del CRM mostrando tu máquina en la lista de conectadas — punto verde, nombre de host, proyecto, "last seen: just now", contador de uptime de sesión.

Mantén la ventana de Terminal/PowerShell abierta — cerrarla detiene el bridge.

Cada guía específica de SO muestra cómo ejecutar el bridge en segundo plano (nohup en Unix, Start-Process -WindowStyle Hidden en Windows). Un modo de servicio persistente (launchd / systemd / Windows Service) está en el roadmap — ver Phase 23.4.

Errores frecuentes — referencia visual

🖼️ Screenshot placeholder — media/bridge/error-gallery.png Especificación: cuadrante compuesto de 4: arriba-izquierda = diálogo "damaged" de macOS, arriba-derecha = diálogo de verificación de install.command, abajo-izquierda = SmartScreen azul de Windows, abajo-derecha = Terminal mostrando ✗ Token expired. Cada uno etiquetado con el error de la tabla anterior.

Qué hace el Bridge realmente

El bridge conecta tu máquina local al relay WebSocket de Arc OS. Los workers del CRM pueden entonces llamar a 5 herramientas en sandbox para acceder a tus archivos:

sequenceDiagram
    participant W as Worker (cloud)
    participant R as Relay (VPS WS)
    participant B as Bridge (tu laptop)
    participant FS as FS local

    W->>R: read_file("./src/index.ts")
    R->>B: llamada de herramienta
    B->>B: validar ruta (sandbox)
    B->>FS: leer archivo
    FS-->>B: contenido
    B-->>R: respuesta
    R-->>W: contenido
    Note over W,FS: Las 5 herramientas siguen el mismo bucle.<br/>execute_command muestra primero el banner amarillo.

Todas las rutas de archivo están en sandbox en el directorio desde donde lanzaste el bridge. Los workers no pueden escapar de él mediante ../.

Modelo de seguridad

Avanzado — flags y entorno

Para scripts de CI o flujos de trabajo basados en variables de entorno:

# Linux / macOS — variable de entorno
CRM_TOKEN="eyJhbG..." ./bridge-linux-x64 --project <project>

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

# Ejecutar desde el código fuente (requiere Bun ≥ 1.0)
CRM_TOKEN="eyJhbG..." bun scripts/bridge.ts --project <project>

Diagnósticos

¿Atascado? Ejecuta estos en orden:

# 1. ¿El VPS es accesible?
curl -s http://62.171.128.248:18888/api/master/health
# Esperado: {"status":"ok","children":N,...}

# 2. ¿Está registrado tu bridge? (reemplaza <token>)
curl -s -H "Authorization: Bearer <token>" \
  http://62.171.128.248:18888/api/internal/bridges
# Esperado: lista JSON que incluye tu nombre de host

Si ambos tienen éxito pero el bridge sigue reconectándose → el problema está entre el bridge y el relay (firewall, VPN, proxy corporativo). Prueba WebSocket directamente:

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

Compilar desde el código fuente (desarrolladores)

# Una sola plataforma
bash scripts/build-bridge.sh linux

# Las 4 plataformas
bash scripts/build-bridge.sh

Los resultados se guardan en dist/bridge-{platform} y se suben al CRM como los binarios servidos en la página Bridge Setup.

Referencia

• API: /api/internal/bridges — listar bridges conectados
• Arquitectura: Phase 23 — Local Gateway
• Código fuente: clients/bridge/ en el repositorio GitHub
• Guías por SO: macOS · Linux · Windows

Mantenido por el equipo de Arc OS. Si te has atascado donde esta guía no ayudó, es un bug — envía un DM al CEO o publica en @arcos_beta_feedback.