# BrowserBridge macOS Quickstart

This is the shortest safe path for a Mac browser host.

## 1. Download Or Clone

Use the public-safe latest tarball for tester installs:

```sh
curl -LO https://pub-94e17e3158894cbba8864e5d1eab3045.r2.dev/downloads/latest.tar.gz
curl -LO https://pub-94e17e3158894cbba8864e5d1eab3045.r2.dev/downloads/latest.sha256
shasum -a 256 -c latest.sha256
```

For source-checkout development:

```sh
git clone https://github.com/MahdiHedhli/browserbridge.git
cd browserbridge
```

## 2. Install Or Update

Preview first:

```sh
./scripts/install-or-update.sh dry-run
```

Install or update the checkout:

```sh
./scripts/install-or-update.sh update --ref main --skip-start
```

For trusted tailnet testing:

```sh
./scripts/install-or-update.sh update --ref main --allow-remote --host <tailnet-ip> --skip-start
```

## 3. Load The Extension

1. Open `chrome://extensions`.
2. Enable Developer Mode.
3. Choose Load unpacked.
4. Select the printed `packages/extension/dist` path.
5. Confirm permissions are exactly `nativeMessaging` and `activeTab`.

Service worker inactive is normal when idle. Registration failures, missing
service worker files, or bare `@browserbridge/*` import errors mean the bundle
must be rebuilt before testing.

## 4. Run Native Doctor

After Chrome shows the extension id:

```sh
npx pnpm@9.15.0 --filter @browserbridge/companion exec browserbridge-companion native:doctor --os macos --extension-id <chrome-extension-id>
./scripts/install-or-update.sh doctor --extension-id <chrome-extension-id>
```

## 5. Start MCP

Loopback:

```sh
npx pnpm@9.15.0 --filter @browserbridge/mcp-server exec browserbridge-mcp http --host 127.0.0.1 --port 7332
```

Trusted tailnet:

```sh
npx pnpm@9.15.0 --filter @browserbridge/mcp-server exec browserbridge-mcp http --host <tailnet-ip> --port 7332 --allow-remote
```

`--allow-remote` does not grant capability. Pairing, short-lived sessions,
exact scopes, approvals, panic checks, tab routing, and audit still apply.

## 6. Verify Status

Use the harness adapter or MCP status tool. A healthy no-tab state may return
`live_unavailable`; that means BrowserBridge is reachable but has no fresh
origin-only active-tab metadata.

## 7. Connect Hermes

Hermes should use the BrowserBridge MCP adapter, not a CDP `/browser connect`
flow.

```sh
hermes mcp test browserbridge
ssh <hermes-user>@<hermes-host> '/opt/hermes-agent/source/venv/bin/hermes mcp test browserbridge'
```

The Hermes adapter should report the current BrowserBridge `buildCommit` and
preserve `live_success`, `live_unavailable`, and explicit demo `mock_success`
without reshaping unavailable state into stale tabs.

## 8. Troubleshoot

```sh
./scripts/install-or-update.sh doctor --extension-id <chrome-extension-id>
npx pnpm@9.15.0 --filter @browserbridge/mcp-server exec browserbridge-mcp runtime:clear-cache --confirm
```

Do not add host permissions, content scripts, broad `tabs`, click/type live
execution, DOM reads, screenshots, or unauthenticated remote listeners to work
around setup failures.