Enroll a device
Last updated
A running relay becomes a workspace when someone redeems the bootstrap invite. That makes the first device the workspace trust root and writes a recovery phrase that only that person will hold. It also starts the transparency log at the genesis fingerprint the relay printed, and everyone else joins by invite afterwards.
Before you start
Have the enrollment URL from first boot and the genesis fingerprint printed next to it. You also need a place to write down twenty-four words other than the machine you are enrolling from.
The URL is single use and expires twenty-four hours after first boot. If it expires unredeemed, the relay can reissue it while the workspace still has no trust root. Once the workspace has one, reissue refuses permanently.
Redeem it
- Install the Mac app on the machine that will be the first admin.
- Open the enrollment URL. The app reads the relay hostname and the fingerprints out of it.
- Compare the genesis fingerprint the app shows against the one the relay printed. They have to match character for character, because later transparency-log verification is measured against this check.
- Write down the recovery phrase, then confirm three of the words by position.
- The app enrolls the device and the relay destroys its genesis private key in the same transaction.
The recovery phrase
The phrase is twenty-four words, generated on the device, per workspace. It holds admin authority and rotates when used. There is no escrow and no operator reset.
We cannot recover a workspace for you, because no key exists anywhere in this system that could. The same property keeps the relay from reading the workspace. Treat the phrase the way you would treat a hardware wallet seed.
Inviting everyone else
Every join uses one primitive. It is a signed authorization plus sealed group information, delivered as a link, with a separate twelve-character code sent another way.
| Half | Delivered how | Why it is split |
|---|---|---|
| The link | However you like, usually email | Holds the sealed group information |
| The code | A different channel from the link | One intercepted channel is not enough to join |
A joiner enters by MLS external commit, so there is no waiting state, no approval queue and no half-joined member. Invites carry scopes. The bootstrap invite carries admin, no scopes, and a twenty-four hour expiry.
If your relay has SMTP configured it can send the link itself. SMTP is unset by default, because a relay holding invitee addresses puts a list of humans inside the blind half of the system.
Devices and identity
A relay has no login, no password and no account record. Identity is possession of a device private key, held in the operating system keychain. A person with two Macs enrolls twice.
The first device enrolled is the permanent trust root, and the last remaining admin cannot be revoked. Add a second admin early. With one admin, a single lost laptop leaves the recovery phrase as the way back in.
Checking the result
Open the encryption panel in the app. It names the relay hostname, the running image digest, whether the access set is enforced, and the safety number for a channel. When two members read the same safety number aloud, they have confirmed that nobody was added silently.
Verify is the longer version of that check. Do it once.