Troubleshooting

Most first-week problems are one of six things. Work down the list in order; the first two cover the large majority.

The bridge shows offline after the laptop slept

Expected and usually self-healing. The bridge keeps an outbound connection; when the machine suspends, that connection dies, and on wake it reconnects on its own retry. Give it a few seconds before doing anything.

If it stays offline:

1. Confirm the machine is actually awake and on a network. A closed lid with the lid-close sleep setting means there is nothing to reconnect.
2. Confirm the bridge process is running. It is registered as a user-level service — a LaunchAgent on macOS, a systemd user service on Linux, a Windows service — so it should come back after login. If you have never logged in since the last reboot, a user-level service has not started yet.
3. Confirm the machine has outbound HTTPS and WebSocket access. Corporate networks and captive portals are the usual culprits.
4. Check the bridge log (below) for a repeated connect failure.

Opening inbound ports is not a fix for this. Both ends dial out.

An agent shows as signed out

Agent logins belong to the agent, not to Helmora. Helmora detects install and authentication posture and reports it — it does not hold or refresh a provider credential.

So when a runtime reports signed out, sign in to that CLI on the bridge machine, as the same user the bridge runs as. That last part is the common trap: a credential you created under a different user account is invisible to the bridge.

Afterwards, re-run the Test step in the agent’s settings. It runs the adapter’s real preflight rather than trusting a cached banner, so it will tell you plainly whether the CLI is missing, unauthenticated, or ready.

The pairing code expired

Pairing codes live for ten minutes and are single-use. That is short on purpose, and it is easy to burn while walking to another machine.

Fix: open Settings → Devices → Pair a bridge and generate a fresh one. The installer URL changes with the code, so use the new one-liner — re-running the old command fails, because the installer endpoints themselves check that the code is live.

The session list looks stale

The bridge is authoritative for sessions; the app is a view. If the list looks wrong, the view is behind.

1. Pull to refresh, or reopen the sessions list.
2. Check that the device selector is on the bridge you expect. Sessions are per-bridge, and a session on your desktop will not appear under your laptop.
3. Check the folder. Claude Code registers one agent per folder, so its sessions are scoped to that folder. Codex, Copilot, OpenCode, and Goose are machine-scoped with folder facets, and their lists behave differently as a result.
4. Sessions started outside Helmora only appear for runtimes that mirror external work. Goose does not — see the runtime pages.

Reconnecting after a network change

Switching wifi, dropping to cellular, or coming off a VPN drops the connection at both ends. Both sides reconnect on their own backoff; a turn that was running keeps running on the bridge while you are away, and the transcript catches up when you return.

If the app reconnects but the bridge still reads offline, the app’s network recovered and the bridge’s did not — treat it as the offline case above and look at the bridge machine.

Pending approvals and questions are rebuilt on reconnect rather than lost, so you can answer them after the reconnection lands.

Where the logs live

On the bridge machine:

~/.helmora/logs/bridge.log

Rotated in place. That file is the first thing to read for anything that looks like “it won’t connect” or “the agent never started”. Look for the adapter name and the session or turn id near the timestamp of the problem.

If you are reporting an issue, the most useful single thing to include is the exact bridge error message, plus which bridge, which adapter, and whether the app was on the relay or a same-machine connection. Get in touch.