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.

On Linux: sign in without a bundle​

The prerequisite above has one exception. On Linux, Set up sync also offers Sign in with a Matrix account instead, and the first-device card on the pairing-code page carries the same option. Enter the server address, your full Matrix ID (like @name:example.com) and the account password, and Lotti signs in, creates the encrypted sync room on that account itself, and lands on the same first-device screen the bundle path ends on. No admin, no tool, no bundle — any Matrix account you control will do, on your own homeserver or a public one.

Two things to know. Use an account set aside for sync, not one you chat with: the sync room is just another room on that account, and everything you write goes into it. And your password is your own here — it stays in this device's secure storage and is never rotated, unlike the bundle above. Only the server you enter sees it, plus the pairing codes you later make under Add device: those carry it, so treat them as the credentials they are. Every further device still pairs from this one with Add a device.