Arc OS Docs Open in app →

Local Bridge — Configuração no macOS

Guia de instalação específico para macOS. Para a visão geral, checklist de pré-voo, erros, modelo de segurança e diagnósticos, veja Local Bridge — Guia de Configuração.

Tempo total: ~60 segundos assumindo que o token já foi copiado.

Primeiro, identifique seu chip

Seu Mac Clique neste botão no CRM Arquivo baixado
Apple Silicon (M1 / M2 / M3 / M4 / M5) macOS (Apple Silicon) bridge-darwin-arm64.tar.gz (~50 MB)
Intel (Mac anterior a 2020) macOS (Intel) bridge-darwin-x64.tar.gz (~50 MB)

Não tem certeza de qual chip você tem? Clique no logo 🍎 (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.

Os passos abaixo são idênticos para ambos os chips. Basta substituir arm64 ↔ x64 nos nomes de pastas e binários.

1. Download

No CRM: Settings → Integrations → Bridge Setup → 🍎 macOS (Apple Silicon) (ou 🍏 para Intel).

O Safari baixa bridge-darwin-arm64.tar.gz e extrai automaticamente para ~/Downloads/bridge-darwin-arm64/.

🎞️ Placeholder de GIF — media/bridge/macos-download.gif Especificação: gravação de tela de 8 segundos — cursor clica no botão 🍎 → barra de progresso do Safari preenche → pasta aparece no Finder.

A pasta contém:

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

2. Execute o instalador

Forma fácil (Finder, sem Terminal)

🎞️ Placeholder de GIF — media/bridge/macos-rightclick-open.gif Especificação: gravação de 12 segundos — Finder aberto em ~/Downloads/bridge-darwin-arm64/, clique com botão direito em install.command, escolhe Open no menu, diálogo "developer cannot be verified" aparece, clica em Open, Terminal abre com o instalador em execução.

  1. Abra ~/Downloads/bridge-darwin-arm64/ no Finder
  2. Clique com o botão direito em install.command → Open
  3. Clique em Open no diálogo "developer cannot be verified"
  4. O Terminal abre e executa o instalador automaticamente

❗ Clique direito → Open é obrigatório no primeiro lançamento. Um duplo clique normal aciona o bloqueio definitivo do Gatekeeper. Após a primeira execução bem-sucedida, o duplo clique funciona normalmente.

Forma avançada (Terminal)

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

3. Conecte

Antes de iniciar, obtenha dois valores no CRM:

O que Onde
Token Settings → Integrations → Bridge Setup → clique em Copy (JWT, TTL de 24h)
Nome técnico do projeto Barra lateral → seu projeto → slug da URL (ex.: o que está em minúsculas com hífens, não o nome de exibição)

O bridge solicitará três valores:

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

🖼️ Placeholder de screenshot — media/bridge/macos-connected.png Especificação: janela do Terminal após a conexão. Linhas visíveis: ✓ Token validated · ✓ Connected to ws://…/ws/local-bridge · Watching <abs-path>. Título da janela mostra Terminal — install.command.

P: Por que informar o nome do projeto se tenho vários? Uma instância do bridge se vincula a um único projeto — os workers daquele projeto leem arquivos apenas do diretório onde você iniciou o bridge (sandbox). Para trabalhar com múltiplos projetos, execute um bridge por projeto em seu próprio diretório.

P: Por que uma URL de servidor? Basta pressionar Enter. O padrão aponta para o relay de produção do Arc OS. A URL customizada é para configurações self-hosted; você não precisa alterá-la.

Se você vir ✓ Connected, está pronto. Vá para o CRM → Bridge Setup e confirme o ponto verde.

❌ Três coisas para NÃO fazer no macOS

🖼️ Placeholder de screenshot — media/bridge/macos-damaged-error.png Especificação: diálogo macOS "bridge-darwin-arm64" is damaged and can't be opened. com botões Move to Trash / Cancel. Anotação: X vermelho sobre Move to Trash, marca verde sobre Cancel.

Não faça Por que Faça em vez disso
Clique duplo diretamente em bridge-darwin-arm64 O Gatekeeper marca como "damaged" — confuso, mas esperado para binários sem assinatura Execute install.command primeiro; ele remove o atributo de quarentena
Clique em "Move to Trash" no diálogo de damaged Você perde o binário baixado Clique em Cancel e use install.command
Arraste a pasta para Applications O bridge precisa executar a partir de onde você o iniciou (raiz do sandbox) Execute diretamente de ~/Downloads/bridge-darwin-arm64/

Executar em segundo plano (daemonizar)

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

Um modo de serviço persistente (launchd) está no roadmap — veja a Phase 23.4.

O que fazer a seguir