Docs / Getting started

Pairing machines

Pairing joins a machine to your fleet. It is also the moment that machine receives the keys to your encrypted drive.

How your machines find each other

Your machines find each other at home or across the internet. The Network page shows three ways separately, each with its own state, so when something fails you can see which way works:

• On your local network, with no setup and no server of any kind.
• Over Tailscale, when it runs on both machines.
• Across the internet, when two machines share no network.

Seeing another machine gives it nothing. To do anything together, two machines have to be paired.

Pair a machine

In this example, atlas is already in your fleet and nova is the new machine.

1. Unlock the drive on both machines. Pairing hands over the drive keys and cannot do that while a drive is locked.
2. On atlas, open Network and press Show a pairing code. It shows a code as text and as a QR code. A code lasts ten minutes.
3. On nova, type the code into the join form and press Join. On a phone, scan the QR instead.
4. On atlas, a banner appears on every page with nova's name, its address, its key fingerprint and a countdown. nova shows its own key too. Check that the two match.
5. Press Approve here on atlas. nova joins the fleet and receives the drive keys.

A sound plays on atlas when a request arrives. You can turn it off with Sound when a machine asks to join in Settings → Network. At most three requests can wait at once.

What a paired machine can do

• Open the shared drive with the keys it was given.
• Send files into your other machines' drop folders and take part in sync. See Sync and backup.
• Chat with your other machines. The right bar lists each paired machine with its own thread. A message to a machine that is off arrives when it is back.
• Use folders you share with it. In Settings → Network you choose whether that is off, whether you pick folders yourself, or whether other machines may ask.

Cameras, screens, microphones and speakers

Using another machine's camera, screen, microphone or speakers is a separate question. The request arrives with a countdown, and if the countdown runs out the answer is no. Always makes it a standing permission, listed on the Network page with a revoke button beside it.

The machine that owns a device decides who may use it. Other machines only hold a copy of that decision, and the copy expires after two minutes. So a revoke takes effect quickly, and a machine that goes offline loses access.

Removing a machine

Remove a machine on the Network page. It still holds the drive key it was given, so rotate the drive key next. After that, it cannot read anything written from then on.

Lock every machine at once

Lock fleet on the Network page locks every machine paired with this one. Each machine reports back: locked, refused with its reason, or offline. An offline machine is locked the moment it is next seen.

Unlock… asks another machine to unlock. It sends no secret. Someone at that machine has to type its lock phrase there, within two minutes.

When pairing fails

"that code expired … show a new one on that machine"

Codes last ten minutes. Press Show a pairing code again.

"that is not the code shown on that machine"

Check the code for typos, or scan the QR.

"unlock encryption on this machine first"

Unlock the drive in the top bar or in Settings → Encryption, then join again.

"Another machine is using this machine's identity"

One machine was set up by copying the other's data folder, so neither can see the other. On the copy, press Give this machine a new identity on the Network page. Its drive and files stay as they are.

"A machine claimed to be atlas with a different key and was refused"

If you reinstalled atlas, this is expected: remove it on the Network page and pair it again. If you did not, something on your network used atlas's name. It was given nothing.