The installer and the app name the problem; this page says what to do. Bridge logs:
journalctl -u hermes-car-voice-bridge (no tokens, audio or transcripts, only stages, lengths and timings).
The installer says Hermes: not reachable at http://127.0.0.1:8642, the app says “Hermes is not reachable.”,
and curl -s http://127.0.0.1:8787/readyz shows "hermes":"unreachable".
hermes gateway; it reports
API server listening on http://127.0.0.1:8642. A gateway that was already running when the installer added
API_SERVER_ENABLED and API_SERVER_KEY needs a restart before it uses them.API_SERVER_HOST and
API_SERVER_PORT in ~/.hermes/.env with HERMES_API_BASE_URL in /etc/hermes-car-voice/bridge.env, then
sudo systemctl restart hermes-car-voice-bridge./readyz can lag behind for half a minute./readyz only checks that the API server answers, not the key. “Hermes rejected the bridge key.” in the app
means HERMES_API_KEY in bridge.env differs from API_SERVER_KEY in Hermes; put the same key in both and
restart the bridge. A re-run of the installer warns about this too.
In the phone’s browser, on mobile data, open https://<your bridge address>/healthz. It should show
{"status":"ok"}.
tailscale serve status should list a proxy to http://127.0.0.1:8787. HTTPS certificates
must be enabled for the tailnet (Enabling HTTPS).http://127.0.0.1:8787, and it has
to run on the bridge machine. curl -s http://127.0.0.1:8787/healthz on that machine tells whether the
bridge itself answers (systemctl status hermes-car-voice-bridge).{"status":"ok"} in the browser but the app still fails: the address in the app must be exactly that origin
(https://host[:port], no path). Pair again and scan the new code.An unreachable bridge never locks you out: the next question simply tries again.
The installer says Speech recognition: still loading the model, first start downloads a few hundred MB, and
/readyz shows "stt":"loading". On its first start the bridge downloads the Whisper model; after that it
only loads it from disk. A question asked in the meantime waits for the model. Wait a few minutes and
check /readyz again. If it stays loading, look for stt: preload failed in the log: the machine may have
no internet access or too little memory (Whisper small needs roughly 400 to 700 MB). An OpenAI-compatible
transcription service avoids the download; see Answers are slow.
| The installer says | What to do |
|---|---|
| Car Voice needs Python 3.11 or newer | Install Python 3.11 or newer from your distribution and run the installer with it, e.g. sudo python3.11 hermes-car-voice/backend/install.py. |
| Run the installer as root | Run it with sudo, as the user that runs Hermes. |
| This machine does not run systemd | Install the bridge by hand, or use backend/deploy/docker-compose.yml. |
| Python’s venv module is missing | sudo apt install python3-venv on Debian and Ubuntu, then run the installer again. |
| No Hermes Agent found | Install Hermes Agent first, or run the installer with --hermes-env PATH (Hermes’ .env file) or --hermes-url http://127.0.0.1:8642. |
| Hermes’ API server is not switched on yet | Answer yes to let the installer add API_SERVER_ENABLED=true and a new API_SERVER_KEY, or add them yourself (setup step 1). Then restart hermes gateway. Without a terminal the answer is no; add --yes. |
| Hermes keeps API server settings in …config.yaml | Run the installer with --hermes-url http://127.0.0.1:8642 (or your port) and type the API server key when asked. |
| Hermes listens on … (API_SERVER_HOST) | The bridge reaches Hermes only on the same machine or over HTTPS. Keep API_SERVER_HOST at its default 127.0.0.1, or use --hermes-url https://…. |
| These bridge settings would not work | The message names the setting, e.g. an --stt-base that is not https://. Nothing was changed. |
| The bridge configuration check failed | The message names the setting in /etc/hermes-car-voice/bridge.env. Fix it and run the installer again; the running bridge was not restarted. |
| The bridge did not answer on …/healthz | The last log lines are shown above the message. More: journalctl -u hermes-car-voice-bridge -n 100. |
| tailscale serve did not succeed | Tailscale’s own message is shown above it, unchanged. Usually HTTPS certificates are not enabled for the tailnet yet (Enabling HTTPS). Then pair: sudo python3 hermes-car-voice/backend/install.py --pair. |
| A phone named ‘phone’ is already paired | Answer yes to give it a new token (the old one stops working), add --replace, or pair another phone with --name tablet. |
| HERMES_API_KEY … differs from API_SERVER_KEY | See Hermes is not reachable: put the same key in both. |
You skipped a setup step. Tap Finish setup: it opens the missing step (microphone or connection).
The bridge no longer accepts the saved token (it was replaced with --replace, removed from the tokens file,
or belongs to another bridge). Pair again (sudo python3 hermes-car-voice/backend/install.py --pair, see
setup step 4) and scan the new code in Settings › Connection ›
Scan QR code.
See The phone cannot reach the HTTPS address.
The address answers, but without the /voice/v2 API this app needs. Update the bridge (see
Updating the bridge). If Settings says “Your bridge ignores this setting until
it is updated” under Spoken replies, the bridge works but predates short and full replies.
| The app says | Cause |
|---|---|
| Hermes rejected the bridge key. | HERMES_API_KEY in the bridge does not match API_SERVER_KEY in Hermes. |
| Hermes is not reachable. | The Hermes API server is not running, or HERMES_API_BASE_URL is wrong. /readyz then shows "hermes":"unreachable". |
| Hermes is busy with other tasks; try again in a moment. | Hermes answered 429, for example because its limit on concurrent runs was reached. |
| Hermes took too long; I stopped the task. | The run took longer than HERMES_TURN_TIMEOUT_SECONDS (default 600). |
| Speech recognition … | The STT provider failed: check its address and key, or switch to local Whisper. |
For anything inside Hermes itself, see the Hermes documentation.
Local Whisper (small) needs several seconds per question on a small CPU. An OpenAI-compatible transcription
service (HERMES_BRIDGE_STT_PROVIDER=openai, or --stt openai for a new installation) is usually well under a
second; your recorded questions then go to that service. The rest of the time is Hermes working; the car screen
shows what it is doing.
The voice says “The full text is in the app”: the reply was longer than the safety net
(HERMES_BRIDGE_SPEECH_MAX_CHARS_SHORT, 700 characters for short replies; HERMES_BRIDGE_SPEECH_MAX_CHARS,
3000 for full replies), or it contained code, which is never read aloud. Choose Full in Settings › Voice ›
Spoken replies for complete answers, or raise the value on the bridge. Bridges before 0.4.0 cut full replies
at 450 characters; a HERMES_BRIDGE_SPEECH_MAX_CHARS line in bridge.env keeps its own value after an update.
Car Voice listens and speaks in the phone’s language. If you speak a different language from the one your phone is set to, pick yours in Settings › Voice › Language.