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.
brew --versionIf 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):
brew update
brew tap tripleclabs/tapDo not prefix the commands below with sudo. Homebrew checks each downloaded product against its pinned SHA-256 checksum.
2. Install and configure Hybrid Bridge
brew install tripleclabs/tap/hybrid-bridge
hybrid-bridge --versionExpect 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:
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:
brew services start tripleclabs/tap/hybrid-bridge
brew services listAsk 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:
brew services restart tripleclabs/tap/hybrid-bridgeThe 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:
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.