Skip to main content

Pairing

pmux pair connects your host to the Pocketmux mobile app through a secure key exchange. This is a one-time setup per host-mobile pair.

Prerequisites
  • You must have run pmux init first (see Initialization).
  • Install the Pocketmux mobile app on your phone.

Running pair​

$ pmux pair
Contacting signaling server...

Scan this QR code with Pocketmux on your mobile device:

█████████████████████████████
█████████████████████████████
████ ▄▄▄▄▄ █▀ █▀▄█ ▄▄▄▄▄ ████
████ █   █ █▄ ██▀█ █   █ ████
████ █▄▄▄█ █ ██▀██ █▄▄▄█ ████
████▄▄▄▄▄▄▄█ ▀ █▄█▄▄▄▄▄▄▄████
████▄▄▀▄█▀▄ ▀ ▄ ▀█   █▄▄▀████
████▀▄ █▄▀▄▀█▀█▄ █▀█▀▀▄▀ ████
█████▄███▄▄█▀▄▄ ▀▄█ █▄██▀████
████ ▄▄▄▄▄ █▄█▀ ▄██▀ ▄▄▄▀████
████ █   █ █▀▄█▀▀▄██ ▄█▀▀████
████ █▄▄▄█ █▀▄█▄▄ ▄█▄█▄█▄████
████▄▄▄▄▄▄▄█▄███▄▄▄█▄██▄█████
█████████████████████████████
█████████████████████████████

Manual pairing code: ABC123

Waiting for mobile device to complete pairing...
Paired successfully with device b5a4d7c6f9e8

The QR code encodes the pairing code, the host's ephemeral X25519 public key, the host device ID, and the signaling server URL in a pipe-delimited format.

Scanning the QR code​

Open Pocketmux on your phone, navigate to "Add Host", and point your camera at the QR code displayed in the terminal. The app reads the pairing payload from the QR code and completes the key exchange automatically.

Manual pairing code​

If QR scanning is not practical — for example, during an SSH session, screen sharing, or in a small terminal window — you can enter the 16-character pairing code manually in the app under "Add Host > Enter Code". The code expires after 5 minutes.

What happens during pairing​

Both devices independently derive the same shared secret from the X25519 key exchange. This secret is stored securely — in the system keychain on macOS or an encrypted file on Linux — and is used to authenticate the WebRTC connection between host and mobile. The signaling server facilitates the exchange but never learns the shared secret.

Re-pairing​

Each host pairs with exactly one mobile device. Running pmux pair when a device is already paired prompts for confirmation before replacing the existing pairing:

A device is already paired: My iPhone (paired 2026-02-28). Replace it? [y/N]

The previously paired mobile receives a device_unpaired notification. A single mobile device can pair with multiple hosts.

Verifying the pairing​

Use pmux status to confirm the pairing:

$ pmux status
Agent:    running (PID 48210)
Service:  installed
Sessions: 0

Paired device: My iPhone
  Device ID:  f9e8d7c6b5a4...
  Paired:     2026-02-28

Troubleshooting​

Common issues
  • Timeout — The pairing code expires after 5 minutes. Ensure both devices have network connectivity and run pmux pair again.
  • Server unreachable — Verify network access. Check the configured server URL with pmux config.
  • QR too small — Widen your terminal window or use the manual pairing code instead.
  • Already paired — If you need to pair a different mobile device, run pmux pair and confirm the replacement when prompted.

Next steps​

Your host is now paired. Use pmux just like tmux — see the CLI Reference for all available commands.