Skip to main content

Your first device

Prerequisite

This page needs a Matrix (Synapse) homeserver you or someone you trust operates, plus admin access to it. If you do not have one, this path is not available to you — and nothing else in Lotti depends on it.

Every device after the first gets its pairing code from a device you already use — that flow is Add a device. The first one is different: there is no other device to mint a code. Lotti's sync is self-hosted, so the first code comes from the server side, created by whoever runs your Synapse homeserver.

What the provisioning tool does​

Lotti ships an admin CLI, the Matrix provisioner, in the repository at tools/matrix_provisioner. Run by a homeserver admin, it:

  1. creates a fresh Matrix account dedicated to sync,
  2. creates the encrypted sync room, and
  3. writes a provisioning bundle — the text Lotti accepts as a pairing code — to a file.

The README next to the tool documents the one-time setup, every argument and the safe ways to supply the admin password. A minimal run looks like:

cd tools/matrix_provisioner
python provision.py \
  --homeserver https://matrix.example.com \
  --admin-user admin \
  --username lotti_sync_user42 \
  --output-file bundle.txt

If you do not run your own homeserver, this step is not yours to do — ask the person who operates the server for the bundle, and treat how it reaches you with the care described below.

Use the bundle as your first pairing code​

On the device that should become your first, open Settings → Sync Settings → Devices and choose Set up sync. Paste the bundle's text into the code field — on a phone, where the camera opens first, choose Paste the code instead to get there. Review what the code describes, then connect — and that is the whole journey for a first device. There is no emoji verification here: verification compares two of your devices, and you only have one. The ceremony makes its first appearance when you pair your second device with Add a device.

Also worth knowing: consuming a fresh provisioning bundle rotates the account password as part of connecting. The bundle file is spent after its first use — the live credential then exists only on that device, and every further device pairs from an existing one with Add a device. Delete the bundle file once the first device is connected; a copy that lingers can no longer sign in, but there is no reason to keep it.

Until that first use, treat the bundle like a password: it signs in to the sync account, so keep it out of chats, screenshots and shared screens.