QR Code Pairing

Pairing connects the app to a PocketCmd Server you run, for end-to-end encrypted sync, server metrics, alerts and teams. You scan a QR code once; after that the device authenticates with its own key and short-lived certificates, with no password to type.

Pairing a server requires PocketCmd Pro. The one-shot pcmd sync import uses the same kind of QR code and works on Free.

The first device to pair becomes the server’s owner. Further devices, yours or your team’s, join with an invite. See Teams.

Before you start

Install PocketCmd Server on the host with the command the app shows under Teams › Set up a new server. It carries the app’s API version, so the installer picks a server the app can talk to:
Terminal window
```
curl -fsSL https://pocketcmd.com/install.sh | sh -s -- --api 1
```
See Server Installation for other ways to install.
The device must reach the host on port 8767, the default. Guest Wi-Fi networks often block traffic between devices.

1. Start the server

On the host, run the binary with no arguments, as the user who should own the server (not root):

pcmd

On its first run it creates the server’s TLS certificate, asks which network interface to listen on if the host has more than one address, prints a QR code and waits for a device. Over an SSH session the QR code is drawn in plain ASCII. You can also copy the pocketcmd:// link printed after Or copy:.

Each pairing code is valid for 60 seconds and works once. When a code expires, the command prints a new one, for up to five minutes. If nothing pairs in that time, it exits without saving anything, and pcmd starts over. See Server Installation.

2. Scan the code

In the app, use either of these:

Add Server › Import from Computer › Scan QR Code. Paste URL takes the pocketcmd:// link instead.
The Teams button on the home screen › Set up a new server › Scan the server’s QR.

On desktop, where there is no camera, both open a Paste link field for the pocketcmd:// link. Opening the link on the device also starts pairing.

Because you are the first to pair, the app asks for Your display name, which is how the team sees you, and a Device name for the team’s device list.

If the server speaks a different API version than the app, pairing stops with a message that names both versions. Install the server with the command the app shows, or update the app. See Versions and compatibility.

3. Finish

The server confirms the device, installs itself as a background service (unless you started it with --foreground) and exits. The app shows Paired with and the server’s name. From then on the device renews its certificate in the background.

How the handshake works

The server creates a one-time pairing token (32 hex characters, valid for 60 seconds, held in memory) and puts it in the QR code with the SHA-256 fingerprint of its TLS certificate:
```
pocketcmd://<host>:<port>/<pairing-token>#<server-fingerprint>
```
The app connects to the server and checks that its certificate matches the fingerprint from the QR code. A different server on the network can’t answer in its place.
The app creates the device’s identity key and a certificate signing request (CSR) for it, and sends the public key, the CSR, the device name and the token to POST /api/pair.
The server checks that the token is valid and unused and that the CSR’s key matches the public key sent, which proves the device holds the private key. It then signs a client certificate valid for 30 minutes and records the device.
The token is consumed. Every later request uses mutual TLS with that certificate plus a short-lived session token.

After 3 failed pairing attempts from one address, the server refuses further attempts from it until 60 seconds have passed since the first failure.

What the device keeps

Item	Detail
Identity key	ECDSA P-256. Created inside the device’s security hardware where it has some (StrongBox or TEE on Android, Secure Enclave on Apple devices, TPM 2.0 on Windows and Linux), where it can’t be exported and signs without entering app memory. Otherwise a software key, sealed with the device’s vault key. It never leaves the device
Client certificate	Valid for 30 minutes and renewed automatically. A device whose certificate expired while it was offline recovers with a signed challenge
Server fingerprint	Pinned at pairing and checked on every connection

A lost or stolen device gives nothing away without the app password: the app lock is mandatory, and the vault key is bound to the device. See App Password & Vault.

Re-pairing after a certificate change

Every device pins the server’s certificate fingerprint. When the certificate changes, run pcmd rotate-server-cert on the host: it restarts the server on the new certificate and prints a re-pair QR code and pocketcmd:// link.

On each paired device, scan the code the same way as in step 2, or open the link. The app recognizes the server, skips the display name and confirms with Re-paired with and the server’s name. The existing server entry is renewed in place, so its sync, vault and team settings stay as they were.

The re-pair code does not expire and can be used by every device, but it only works for devices the server still lists as active. New devices join with an invite instead. Until a device has re-paired, the app marks the server Needs re-pair.

Removing a device

A device can leave on its own, or be removed by someone else:

Unpair from this server, in the app, removes the pairing from that device. The server marks it as having left; it can come back later with a new invite.
Revoke device, by an admin or the owner in the app, or with pcmd revoke-device on the server, is permanent for that device’s key. The app has to be reinstalled before the device can join again with a new invite.

pcmd revoke-device            # pick from a list
pcmd revoke-device a1b2c3d4   # by public key fingerprint prefix

Either way the device is refused on its next request, because the server checks the device list on every call rather than waiting for the certificate or session token to expire.

Troubleshooting

Problem	Fix
The QR code won’t scan	Enlarge the terminal font or the window, run with `--qr-invert` on a dark terminal without color support, or paste the `pocketcmd://` link from the `Or copy:` line
Connection refused or timeout after scanning	Check that the device can reach the address in the QR code and that port `8767` is open. The server listens on one interface: pick one the device can reach with `--host`, or see Reaching the server from outside your network
The token expired	Scan the newest code: the first run replaces it every 60 seconds. After five minutes, run `pcmd` again
Pairing refused because the server already has an owner	The first-run QR code is only for the first device. Add more devices with an invite: `pcmd invite` or the app’s invite flow
Certificate fingerprint mismatch	The server’s certificate changed since the device paired. Scan the re-pair code from `pcmd rotate-server-cert` (see Re-pairing after a certificate change)
Pairing stops with a message about the API version	The server and the app speak different API versions. Reinstall the server with the command the app shows (`--api` with the app’s version), or update the app
`pcmd: command not found`	Run the installer again: `curl -fsSL https://pocketcmd.com/install.sh \| sh -s -- --api 1`