---
title: "Pair with OpenCode Mobile"
description: "Scan a single-use QR code, approve the claiming device, re-pair a machine, remove a saved connection, and handle a lost phone or browser credential."
canonical: "https://opencodecloud.link/docs/pairing/"
lastUpdated: "2026-10-19"
---
Pairing connects one machine running Cloud Link to one Cloud Link account in
OpenCode Mobile. The machine operator must approve the device before the tunnel
starts.

## Before you pair

- The connector is installed and running on the machine.
- OpenCode Mobile was installed from the App Store or Google Play.
- A Cloud Link subscription is active, or you are ready to purchase or restore
  one.
- You can see both the computer screen and the phone.

## Pair a phone

1. Open the connector popover or tray menu.
2. Choose **Pair device** if a QR code is not already visible.
3. In OpenCode Mobile, open **Settings → Cloud Link**.
4. Choose **Subscribe** or **Restore purchases** if the app asks.
5. Tap **Scan QR code** and scan the connector code.
6. On the computer, review the device name in the approval prompt.
7. Choose **Approve** to start the tunnel, or **Deny** to reject the claim.

The tunnel does not start while approval is pending. A denied claim is retired
and the connector can generate a new code.

Pairing codes are single-use and expire after five minutes. The QR code does
not contain the tunnel credential. The connector receives its machine-scoped
tunnel token only after approval.

## What the app saves

After approval, the app saves the connection profile: the stable public URL,
machine identity, and a signed device credential with an expiry. The credential
is machine-scoped and presented as HTTP Basic authentication; the connector
verifies it locally.

The control plane does not store a per-device secret. There is no separate
per-device revocation command: deleting the machine retires its tunnel and DNS
record, and credentials expire on their own.

## Re-pair the machine

Use **Pair device** when you need a fresh QR code, for example after changing
the proxy port or moving the installation. Re-pairing:

- preserves the installation identity and usually the same public hostname;
- interrupts the current connection;
- requires a new phone claim and a new approval on the machine.

If a saved credential is rejected, use **Pair device**,
**Settings → Remove saved connection**, or the CLI `--reset` option. Invalid
credentials do not trigger an automatic registration or reset.

## Remove a saved connection

**Settings → Remove saved connection** forgets the pairing on this computer.
The machine stays in your Cloud Link account, and local settings and services
remain. The connector stops trying to connect until you pair again. The action
does not contact the control plane.

This is useful when a subscription lapses or a tunnel is suspended and you do
not want repeated retries.

## Remote browser access

Remote browsers use a separate credential generated by the connector:

- public URL: `https://m-<random>.opencodecloud.link`
- username: `browser`
- password: a random 64-character value

Show or copy these values from the popover. Regenerating the password invalidates
existing browser logins without changing the phone credential. See
[Remote browser access](/docs/browser-access/).

## If a phone is lost

- Device credentials expire on their own.
- Regenerate the browser password to sign out remote browser sessions.
- Delete the machine in OpenCode Mobile to retire its tunnel and DNS record.
- Pair a replacement phone after the machine is available again.

Per-device revocation is not implemented. Treat the store account, QR codes,
pairing links, and browser password as sensitive.

## Troubleshooting

| Symptom | What to check |
| --- | --- |
| No QR code appears | Wait for startup, then choose **Pair device** |
| QR code expired | Generate a fresh code; codes last five minutes |
| App waits for approval | Approve or deny the device on the computer |
| QR code is rejected | Use a code from the matching environment and a current connector |
| Machine is listed but cannot connect | Confirm the connector is running and online |
| Tunnel credentials rejected | Re-pair or remove the saved connection, then pair again |
| Phone was replaced | Pair the new phone; the old credential expires |

For more, see [Troubleshooting](/docs/troubleshooting/) and the
[OpenCode Mobile Cloud Link guide](https://getopencode.app/docs/cloud-link/).