Pair a bridge

A bridge is the piece of Helmora that runs on your own computer. 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 does not touch your provider logins, your repositories, or the agents’ own transcript stores. 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.