Local Bridge — Guia de Configuração

Conecte sua máquina local ao Arc OS em menos de 90 segundos. Os workers na nuvem leem e editam arquivos no seu computador por meio de um único binário — sem Docker, sem Bun, sem toolchain de compilador.

Phase 23.2 · Última atualização: 2026-05-14 · Testado em macOS 14+, Ubuntu 22+, Windows 11

Escolha seu sistema operacional — vá direto para os passos

Seu computador	Abra este guia
macOS (Apple Silicon ou Intel)	Local Bridge — Configuração no macOS
Linux (x64 ou arm64)	Local Bridge — Configuração no Linux
Windows 10 / 11	Local Bridge — Configuração no Windows

O restante desta página aborda o que é comum a todas as plataformas: checklist de pré-voo, o que o bridge realmente faz, erros comuns, modelo de segurança e diagnósticos. Leia uma vez; volte quando algo der errado.

▶ Assista ao walkthrough de 90 segundos

🎬 Placeholder de vídeo — O embed do Loom ficará aqui assim que for gravado. Nome do arquivo: bridge-walkthrough-2026-05.mp4 · 90s · narração do CEO · legendas em EN. Referência: veja lista de mídia §1.

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

O que você terá ao final

Duas janelas lado a lado, ambas mostrando "conectado":

🖼️ Placeholder de screenshot — media/bridge/success-state.png Especificação: tela dividida — esquerda = Terminal exibindo ✓ Connected to ws://… as <project>, direita = página Bridge Setup do CRM com ponto verde e Online ao lado do nome da sua 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 /     │
└─────────────────────────────────┘  └───────────────────────────────────┘

Checklist de pré-voo

Antes de começar, reúna estas informações no CRM:

🖼️ Placeholder de screenshot — media/bridge/where-to-find-token.png Especificação: página Settings → Integrations do CRM com o botão "Copy" destacado por uma seta vermelha + círculo. Campo de token parcialmente ocultado (mostrar apenas eyJhbG...***...xyz).

Passo 0 — O que você está baixando

O Local Bridge é um único arquivo binário que você executa no seu computador. Não há assistente de instalação, nenhum serviço de sistema, nenhum direito de administrador necessário. Você baixa um arquivo, clica duas vezes (ou executa pelo terminal) e pronto.

Sistema operacional diferente = binário diferente. É por isso que a página Bridge Setup no CRM exibe 4 botões — cada um baixa um arquivo diferente compilado para aquele sistema operacional + arquitetura de CPU. Escolher o errado fará com que seu computador se recuse a executar (Exec format error no Linux, damaged no macOS, not a valid Win32 application no Windows).

🖼️ Placeholder de screenshot — media/bridge/bridge-setup-page-4-buttons.png Especificação: página Settings → Integrations → Bridge Setup do CRM mostrando 4 botões de download em linha: 🍎 macOS (Apple Silicon), 🍏 macOS (Intel), 🐧 Linux (x64), 🪟 Windows (x64). Campo de token acima com botão Copy. 1280×720, modo claro. Anotação: círculo vermelho ao redor do botão 🍎 como exemplo de seleção do usuário.

Tamanho do download e tabela de arquivos

Seu computador	Clique neste botão	Arquivo baixado	Tamanho
Mac com Apple Silicon (M1/M2/M3/M4/M5)	macOS (Apple Silicon)	bridge-darwin-arm64.tar.gz	~50 MB
Mac mais antigo (Intel, anterior a 2020)	macOS (Intel)	bridge-darwin-x64.tar.gz	~50 MB
Laptop Linux / VM / servidor	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 com Windows 10/11	Windows (x64)	bridge-windows-x64.exe	~55 MB

Por que arquivos (.tar.gz) no macOS/Linux, mas .exe direto no Windows? O macOS coloca em quarentena binários baixados sem assinatura com um erro enganoso de "damaged". O arquivo compactado inclui o binário + um pequeno script install.command que remove a quarentena para você. O Windows usa o SmartScreen em vez disso — você clica em um diálogo, sem arquivo compactado necessário.

Escolha sua plataforma — árvore de decisão

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

Não sabe qual chip tem no Mac? Clique no logo 🍎 no canto superior esquerdo → About This Mac → procure "Chip: Apple M1/M2/M3/M4/M5" (Apple Silicon) ou "Processor: Intel Core …" (Intel). Na dúvida: Apple Silicon — todo Mac vendido desde novembro de 2020.

Depois de estar em execução

🖼️ Placeholder de screenshot — media/bridge/crm-bridge-list.png Especificação: página Bridge Setup do CRM mostrando sua máquina na lista de conectados — ponto verde, hostname, projeto, "last seen: just now", contador de tempo de sessão.

Mantenha a janela do Terminal/PowerShell aberta — fechá-la para o bridge.

Cada guia específico de sistema operacional mostra como executar o bridge em segundo plano (nohup no Unix, Start-Process -WindowStyle Hidden no Windows). Um modo de serviço persistente (launchd / systemd / Windows Service) está no roadmap — veja a Phase 23.4.

Erros comuns — referência visual

🖼️ Placeholder de screenshot — media/bridge/error-gallery.png Especificação: composição em 4 quadrantes: superior esquerdo = diálogo "damaged" do macOS, superior direito = diálogo de verificação do install.command, inferior esquerdo = SmartScreen azul do Windows, inferior direito = Terminal mostrando ✗ Token expired. Cada um rotulado com o erro da tabela acima.

O que o Bridge realmente faz

O bridge conecta sua máquina local ao relay WebSocket do Arc OS. Os workers do CRM podem então chamar 5 ferramentas com sandbox para acessar seus arquivos:

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.

Todos os caminhos de arquivo ficam em sandbox no diretório onde você iniciou o bridge. Os workers não conseguem escapar via ../.

Modelo de segurança

Avançado — flags e variáveis de ambiente

Para scripts de CI ou fluxos baseados em variáveis de ambiente:

# 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>

Diagnósticos

Com problemas? Execute estes comandos em ordem:

# 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

Se ambos funcionarem mas o bridge continuar reconectando → o problema está entre o bridge e o relay (firewall, VPN, proxy corporativo). Teste o WebSocket diretamente:

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

Build a partir do código-fonte (desenvolvedores)

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

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

Os arquivos gerados ficam em dist/bridge-{platform} e são enviados ao CRM como os binários disponíveis na página Bridge Setup.

Referência

• API: /api/internal/bridges — listar bridges conectados
• Arquitetura: Phase 23 — Local Gateway
• Código-fonte: clients/bridge/ no repositório GitHub
• Guias por sistema operacional: macOS · Linux · Windows

Mantido pela equipe Arc OS. Se você ficou preso onde este guia não ajudou, isso é um bug — mande uma mensagem direta para o CEO ou poste em @arcos_beta_feedback.