Pair a bridge

A bridge is the piece of Helmora that runs on your own device. It hosts the adapters, talks to the agent CLIs, and reaches your files. Pairing is how a bridge proves it belongs to your account.

The pairing code

In the app, open Settings → Devices → Pair a bridge. The account service mints a six-digit code and shows you the installer one-liner with the code already in the URL.

Three properties matter:

Ten minutes. After that the code is dead, not renewable.
Single-use. Claiming it consumes it.
Session-bound. Only a signed-in account can mint one, which is what makes holding a live code sufficient authorization to fetch the installer at all.

The code is bootstrap authorization, not a standing secret. Once the bridge has claimed it, the bridge holds its own device-scoped credentials and the code is irrelevant. If a code expires before you run it — easy to do while walking to another machine — just generate a fresh one; the one-liner changes with it.

What the installer does

The one-liner fetches a small launcher, which downloads the real installer body and runs it with your pairing code, account URL, and relay URL already filled in. The installer then:

Installs the bridge into a per-user directory on that machine.
Registers it to start on login and restart on crash — a launchd LaunchAgent on macOS, a user-level systemd service on Linux, and a Windows service on Windows (which is why the Windows one-liner insists on an elevated PowerShell).
Claims the pairing code, binding the machine to your account as a device.
Sets up the auto-updater — a fifteen-minute poll that only pulls changes whose CI has passed. Nothing lands on your machine from a red build.

When it finishes, the device appears in the app and you can run Add agent against it. See Getting started.

Because the bridge runs as a user-level service, it comes back after a reboot without you doing anything. It also means the bridge runs as you, with your permissions and your agent logins — treat it like any other developer tool you install.

One bridge per machine

Helmora’s unit of “somewhere my code lives” is a bridge, not a tunnel. Pair one on every machine whose agents you want to reach: a laptop, a desktop, a workstation at the office. Each shows up as its own device.

This is deliberate. Keeping a bridge next to the code it serves means provider credentials, working directories, agent processes, and transcripts all stay on the machine that owns them. The device you select when adding an agent is the machine whose PATH, folders, logins, and agent registry are used — so the selector is meaningful rather than cosmetic.

The alternative shape — one bridge tunnelling into some other machine’s agent daemon — is not supported. Run a bridge there instead.

Removing a bridge

Uninstalling reverses what the installer registered: the service, the auto-update job, and the install directory. It then asks whether to also delete Helmora’s data on the machine:

Keep data is the default. The device stays in your account, shown as offline, and reinstalling reconnects it as before.
Delete data disconnects the device from your accounts and removes its agents from them. It also deletes the bridge’s settings, logs and caches, the agent sign-ins you made in Helmora, and the chats saved with them. If an account cannot be reached, the data is deleted anyway, and the device stays listed there until you remove it in Settings → Devices. When something stays, such as a chat’s working copy with changes you have not committed or an account that did not answer, the uninstaller shows you a notice naming it; after a complete delete there is none.

Either way, uninstalling does not touch your repositories, or the ~/.claude and ~/.codex folders your own provider logins and transcripts live in. Removing the device from the app revokes its account credentials, so a stale copy can no longer connect.

Where next

Architecture — what the bridge is responsible for, and what it deliberately isn’t.
Remote access — reaching a paired bridge from another network.
Troubleshooting — pairing and connection problems.