Pairing devices

Offsite has no account, so there is nothing to log in to. A device reaches a host because you authorised it on that host. Each host keeps its own list, and you can take any entry back: see Device access.

There are three ways in. Pairing with a QR code or a host code authorises the device in the same step. A host you add with a password or your own SSH key asks you once.

Pair with a QR code

1. In the Mac app, open the host’s ⋯ menu and choose Show phone QR.
2. On the iPhone, choose Scan from Mac (on first launch, or from the + in the host list) and point the camera at the code on the Scan on your phone sheet.

The phone gets the host’s address and a one-time pairing secret, and the host records the phone’s own key. From then on the phone connects by itself, over whichever path is reachable: local network, Tailscale or the relay.

Passwords are never in the QR code.

Pair with a host code

A host code is eight characters, shown as X3YK-47Z3. It works where a camera does not: a server in a terminal, a host in another room, a second Mac.

• Where it is shown: on the host, offsite-host setup connect prints the current code next to a QR code and updates it live. A host-only install (setup.sh) ends on the same screen. A host with its relay on shows a code, and so does a Mac host for devices on its local network.
• Where you type it: on the iPhone, into the Host code field on the first screen, or choose Enter Host Code from the + in the host list. On a Mac, Add Host → Connect to Existing Host…, which also takes a pasted QR payload.

The app looks the code up through the relay, and on the local network it asks every Mac host it can see. Only the host that issued the code accepts it.

One code, one device, ten minutes

The QR secret and the host code belong together, and both are single-use. The host replaces them:

• right after a device paired with them,
• after about ten minutes, whether anyone used them or not,
• after you revoke a device,
• whenever the host’s relay service starts.

The host code

X3YK-47Z39MHT-2QXFR7KD-8WPAC4NZ-6TJEH8VB-3SGMworks once, for about ten minutes

1. a new code when
2. a device paired with it
3. ten minutes passed
4. a device was revoked
5. the relay service started

A host code works once and for about ten minutes; the host replaces it after a pairing, a revoke or a restart of its relay service.

A photo of yesterday’s code is worth nothing. For each device, read the current code or show a fresh QR.

Hosts you add with a password or an SSH key

When you add a server with Add Remote Host…, Offsite connects with the password or the SSH key you gave it, and then asks one question: Authorize this device on host?

Authorize this device gives the host a key for this device. Offsite then connects faster, switches networks on its own, reaches the host from anywhere when the host’s relay is on, and needs no password for that path. The password keeps working as before.

Not now keeps the plain SSH connection. You can authorise later from the host’s ⋯ menu with Authorize this device….

This Mac

The Mac you set up as a host is the host itself and reaches it through a local key. Its host menu shows no authorisation line and no revoke.

Per host, not per fleet

Each device pairs with each host separately. Pairing your iPhone with the Mac at home says nothing about the VPS: pair with that host too.

If pairing fails

• “The host code was already used or has expired”, or “No host on this network accepted this code”: the code changed since you read it. Read the current one from offsite-host setup connect and enter it again, or show a fresh QR.
• “Access revoked”: the host no longer accepts this device. Pair again with a fresh code; see Device access.
• An error mentioning Remote Login comes from an older message text. On a current host Remote Login plays no part, and the message means this device is not authorised yet.

Details

• The host’s relay service redeems the pairing secret on every path (local network, Tailscale and relay), so the first connect works whichever path wins. Hosts with the relay switched off pair too.
• Before the app sends a code or a token, it checks the host’s key against the pairing ID it was given, so a code only ever reaches the host it belongs to.
• Authorisations live in ~/.offsite/device-authorizations.json on the host: one record per device with name, how it was added (app, pairing, relay, this-mac for a Mac host’s own key, migration for devices paired before host 0.9.0), and since when. A revoked record stays, marked revoked.
• ~/.offsite/devices.json is a different list: the devices that receive notifications, with their per-device settings.
• A host key that changes, for example after a VPS rebuild, needs your confirmation; the app never reconnects to a changed key on its own.