QR pairing

Current iOS connects to self-hosted sync by scanning a QR code, with no manual server or token entry. Codes are generated only on the server, never in the app.

1. Generate a server code

Deploy or update the sync service first. From its running Compose directory, run:

docker compose exec sync /tempo-sync pair --server https://your-sync-domain.example

Use your public HTTPS base URL, without an API path. The command displays a QR code and expiry time in the terminal. You do not need to copy a sync token into the command.

For this repository's 1Panel deployment, use the host terminal:

cd /opt/1panel/docker/compose/tempo-services
docker compose exec sync /tempo-sync pair --server https://your-sync-domain.example

The command directly runs the binary inside the container; no container shell or separate QR tool is required.

2. Scan in the app

1. Install an iOS build with QR pairing support.
2. Open Settings → Self-hosted Sync → Scan to pair.
3. Allow camera access and scan the terminal code.
4. Check the server address, then confirm.

The app verifies the connection, saves it, and starts automatic sync. Opening the scanner does not clear tasks. After confirmation, local and server data are merged using the sync rules.

Expiry and safety

• Codes expire after 5 minutes and can be used once.
• Generate a new code for each device.
• A new code revokes the previous unused invitation, not existing paired devices.
• Restarting the server invalidates unused invitations, not saved connections or data.
• The QR does not contain the long-lived sync token, but it can authorize a device while valid. Do not share it publicly.

Changing servers and permissions

Choose Pair with another QR code to change servers. The previous connection is replaced only after successful verification. Failed scans or verification do not overwrite it.

If camera permission is denied, open iOS Settings from the prompt, allow access, and scan again. There is no manual token-entry or paste fallback.

Older installed apps need a newer native iOS build; OTA page content cannot add the camera scanner or permission.

Troubleshooting

Problem	Action
Code used or expired	Generate a new code on the server
Server does not support pairing	Update the sync service first
Invalid QR	Scan a Tempo code generated by the command above
Connection failed	Check public HTTPS, certificates, and network access
QR is cut off in the terminal	Widen the terminal and preserve its quiet border
Revoke a paired device	The current service uses one shared token; rotating it requires re-pairing all devices