On this page

Hybrid Bridge on macOS

1. Prepare Homebrew

Open Terminal from Applications → Utilities. These commands run on the Mac, not in a Windows PowerShell or Linux SSH session. Use your normal Mac user account.

Terminal
brew --version

If Terminal says brew is not found, ask IT to install or finish setting up Homebrew using the instructions at brew.sh. Follow its final PATH setup instructions and open a new Terminal window. An existing Homebrew installation may simply need its PATH setup completed; do not install a second copy unnecessarily.

Update Homebrew, then add the official CoCoCo package source (called a tap):

Terminal
brew update
brew tap tripleclabs/tap

Do not prefix the commands below with sudo. Homebrew checks each downloaded product against its pinned SHA-256 checksum.

2. Install and configure Hybrid Bridge

Terminal
brew install tripleclabs/tap/hybrid-bridge
hybrid-bridge --version

Expect hybrid-bridge v2.2.0. Installation alone does not configure or start the bridge. Save the provisioning bundle assigned to this bridge as a protected file on the Mac.

Replace /path/to/bridge-bundle.b64 with your downloaded file's actual path. Keep the quotes if the path contains spaces:

Terminal
hybrid-bridge configure \
  --path "$(brew --prefix)/etc/hybrid-bridge/controller.env" \
  "/path/to/bridge-bundle.b64"

The --path option places the configuration under Homebrew and the certificates in an adjacent certs folder. Do not paste the bundle contents into the command. If provisioning fails, stop and ask your contact to check the error before retrying: a one-time bundle may already have been used.

After provisioning succeeds:

Terminal
brew services start tripleclabs/tap/hybrid-bridge
brew services list

Ask your contact to confirm that the bridge appears connected, then test an agreed integration. A service listed as started does not prove cloud connectivity. If the service was started before configuration existed, configure it first and then run:

Terminal
brew services restart tripleclabs/tap/hybrid-bridge

The Homebrew service runs as your Mac user and starts at login. It does not start before login at system boot. Keep that user logged in and agree the Mac's sleep settings with IT for continuous operation. Do not use sudo brew services to change the service account. If the installation must run unattended before anyone logs in, use the Linux or Windows service route agreed with your implementation team.

3. Find configuration and logs

Run brew --prefix to find the installation base. It is normally /opt/homebrew on Apple Silicon and /usr/local on Intel. Bridge configuration, state and log directories are restricted to the installing user.

Item Path beneath the Homebrew prefix
Bridge command bin/hybrid-bridge
Bridge configuration and certificates etc/hybrid-bridge/
Bridge persistent state var/lib/hybrid-bridge/
Bridge logs var/log/hybrid-bridge/

To read recent Bridge errors:

Terminal
tail -n 100 "$(brew --prefix)/var/log/hybrid-bridge/error.log"

Custom paths in the configuration file can override state defaults. Keep the original bundle protected according to site policy, and retain generated configuration and certificates. See Updates and existing installations for upgrades, migration and removal.