hermes-native-bridge

hermes-native-bridge is the host-side companion CLI for running Hermes Native Bridge on the Mac or server where Hermes is available.

It is not an iOS or macOS app dependency. Apple clients connect to an already running Bridge over the scoped HTTP contract; they do not install npm, run Node, run Python, or download Bridge code at runtime.

Install

npm install -g hermes-native-bridge

For one-off use:

npx -y hermes-native-bridge@latest status

Commands

hermes-native-bridge setup
hermes-native-bridge setup --dev-lan-plaintext
hermes-native-bridge start
hermes-native-bridge status
hermes-native-bridge pairing
hermes-native-bridge logs bridge 120
hermes-native-bridge token
hermes-native-bridge doctor
hermes-native-bridge autostart status
hermes-native-bridge autostart on
hermes-native-bridge autostart off
hermes-native-bridge update check
hermes-native-bridge update apply
hermes-native-bridge restart
hermes-native-bridge smoke

| Command | Purpose | | --- | --- | | setup | Configure the local Bridge environment and pairing settings. | | setup --dev-lan-plaintext | Enable fixed-port same-Wi-Fi development pairing for trusted local devices. | | start | Start Bridge or reuse an existing Bridge process. | | status | Print safe Bridge and Hermes status. | | pairing | Print the local pairing descriptor when available. | | logs bridge 120 | Show recent Bridge logs. | | token | Show token source, status, and fingerprint only. Raw tokens are never printed. | | doctor | Print safe host-side Bridge diagnostics. | | autostart status | Show whether the macOS user LaunchAgent is enabled. | | autostart on | Enable the macOS user LaunchAgent for Bridge. | | autostart off | Disable the macOS user LaunchAgent for Bridge. | | update check | Compare the installed Bridge package with npm latest. | | update apply | Install hermes-native-bridge@latest on this Hermes host. | | restart | Restart Bridge and verify status. | | smoke | Run Bridge contract and redaction smoke checks. |

Pairing

After Bridge is running, pair the native client with the Bridge endpoint shown by:

hermes-native-bridge pairing

Development LAN pairing is intended only for trusted local testing. Remote or release-style access should use HTTPS.

Security Boundary

• Bridge runs on the Hermes host and exposes scoped, redacted APIs.
• Loopback HTTP is acceptable for local development.
• Remote profiles should use HTTPS.
• Tokens, API keys, passwords, OAuth files, private keys, and raw provider secrets must not appear in UI, logs, diagnostics, README examples, or smoke output.
• Missing operational fields should remain missing or be marked as not collected; Bridge should not fabricate Hermes state.

API Shape

Common endpoints exposed by Bridge include:

| Endpoint | Purpose | | --- | --- | | GET /v1/status | Bridge and Hermes status. | | GET /v1/bridge/pairing | Liveness and pairing descriptor. Trusted local development requests can include pairing payload data. | | POST /v1/auth/pair | Exchange a pairing code for app credentials. | | POST /v1/auth/refresh | Refresh app credentials. | | POST /v1/auth/revoke | Revoke app credentials. | | GET /v1/voice/summary | Return redacted Hermes STT/provider configuration. | | POST /v1/voice/transcribe | Transcribe user-recorded audio through the host Hermes STT provider. |

The native client should treat Bridge and any direct Hermes API replacement as the same scoped, redacted HTTP contract.

Requirements

• Node.js 18 or newer for the CLI wrapper.
• Python 3 on the Hermes host for the Bridge server.
• A local or remote Hermes environment available to the host.