Enroll a device
Last updated
A running relay is not yet a workspace. Redeeming the bootstrap invite makes the first device the workspace trust root, writes a recovery phrase that only that person will ever hold, and starts the transparency log at the genesis fingerprint the relay printed. Everyone else joins by invite afterwards.
Before you start
Have three things in front of you: the enrollment URL from first boot, the genesis fingerprint printed next to it, and a way to write down twenty-four words that is not the machine you are enrolling from.
The URL is single use and expires twenty-four hours after first boot. If it expires before anybody redeems it, the relay can reissue while the workspace still has no trust root, and refuses permanently once it has one.
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; this is the check a later transparency-log verification is measured against.
- 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
Twenty-four words, generated on the device, per workspace. They hold admin authority, they rotate when used, and there is no escrow and no operator reset.
We cannot recover a workspace for you. Not as a policy, but because no key exists anywhere in this system that could, which is the same property that makes the relay unable to read the workspace in the first place. Treat the phrase the way you would treat a hardware wallet seed.
Inviting everyone else
One primitive covers every join: 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 moment where a half-joined member exists. Invites carry scopes; the bootstrap one carries admin, no scopes, and a twenty-four hour expiry.
If your relay has SMTP configured it can send the link itself. It is unset by default, because a relay holding invitee addresses is a list of humans inside the blind half of the system.
Devices, not accounts
There is no login, no password and no account record on a relay. Identity is possession of a device private key, held in the operating system keychain, and 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: a workspace with one is a workspace one lost laptop away from needing its recovery phrase.
Checking the result
Open the encryption panel in the app. It names the relay hostname, the running image digest, whether the access set is being enforced, and the safety number for a channel. Two members reading the same safety number aloud have confirmed that nobody was added silently.
Verify is the longer version of that check, and it is worth doing once.