Pair Phones and Recover Keys
Claim or restore your Decisions identity, save and verify a recovery kit, pair a phone, run the setup check, enroll a Remote Host, and revoke a device or rotate keys.
Decisions' encryption depends on keys, and the keys depend on devices. This computer becomes the relay's owner when it claims it: it holds the relay's keys and approves every phone you pair. Each phone, and each Remote Host you enroll, gets keys of its own. This page covers claiming the relay, keeping a way back if this computer is lost, pairing phones, checking the whole loop works, and taking a device away.
Claim or Restore
After a check, Connection offers the next step that fits what it found:
| The relay is | What to do |
|---|---|
| One the guided deploy just created | Nothing. Daintree claims it with the secret it was handed. If that didn't finish, press Finish the claim. |
ready to claim | Enter its CLAIM_SECRET under Claim secret and press Claim relay. Daintree sends the secret once and keeps no copy. |
claimed, by you on another computer | Under Restore from a recovery kit, press Choose kit…, enter its passphrase and press Restore identity. This moves the owner's identity to this computer; it isn't a way to add a second one. |
A relay can be claimed only once. The computer that claims it becomes its owner. To have agents on another machine ask you questions, connect to it as a Remote Host rather than restoring the kit there. If the relay doesn't confirm the claim (<host> didn't confirm the claim), the keys stay on this computer; claim again with the same secret to finish.
Restoring checks that the kit opens, that it holds that relay's owner identity, and that the relay still lists it as its owner, all before anything is saved. A kit saved with the command-line tool's decisions recovery export works too.
Daintree seals the keys with your system keychain. On Linux without a working keyring, it asks Use the weaker key storage? before going on. That uses a fixed key, which protects the keys only from someone who can't read this computer's files.
Save and Verify a Recovery Kit
A recovery kit is a file holding this computer's Decisions keys, locked with a passphrase you choose. It's how you make a new computer the relay's owner. With a relay connected, until a kit is verified and the setup check has passed, Connection shows Setup isn't finished, and its Save recovery kit button takes you to the kit form under Data.
- Under Save a recovery kit, enter a passphrase of at least 12 characters and press Save kit…, then choose where to save the file. Daintree keeps neither the file nor the passphrase.
- Under Verify a saved kit, choose the file you just saved, enter its passphrase and press Verify kit. Daintree checks that it opens, holds this computer's identity and has every key this computer holds now.
Saving alone doesn't count as verified. Keep the kit somewhere other than this computer, such as a password manager. If you revoke a device or rotate keys later, the old kit lacks the new key, so save and verify a new one. The relay's key recovery guide covers losing a phone or losing everything.
A recovery kit isn't the same as Export decision history. The kit holds keys; the export holds the questions and answers stored on this computer.
Pair a Phone
On iPhone and iPad, install the phone app first and pair from the installed app. iOS keeps a Home Screen app's storage apart from Safari's, so a pairing made in a Safari tab stays in Safari, and only the installed app can show notifications.
- Under Devices, press Pair a phone.
- On your phone, scan the QR code with the camera, or open the invitation in the installed app. It works once and lasts five minutes. Copy link gives you the same invitation as a link, if you'd rather paste it on the phone.
- On the phone, tap Pair this device. It shows six digits, and Daintree shows the digits it computed from the phone's keys. Press Approve only if they match. Otherwise press Decline.
- In the phone app's Settings, turn on notifications. Without them, the setup check stops at its push step.
The digits are the security check: they prove the phone you're holding is the one that answered the invitation. Closing the dialog before approving forgets the invitation and asks the relay to reject it, and if that request doesn't get through, the invitation still expires.
Every paired phone or tablet can read and answer every question your agents ask, and every enrolled Remote Host can read them. Device rows show when the relay last saw each one, and Notifications on or No notifications. That says whether the relay holds a push subscription for the device, which isn't the same as proving notifications appear. A relay holds at most twelve devices, and this computer and every enrolled Remote Host count toward that, not just phones.
Install It on Your Phone
The phone app is a web app the relay serves, so there's nothing to download from an app store.
- iPhone and iPad: you need iOS 16.4 or later. Open the relay's address in Safari, tap Share, then Add to Home Screen, and open Decisions from the Home Screen from then on, pairing included. iOS delivers notifications only to the Home Screen app, not to a Safari tab.
- Android: Chrome offers its own install prompt.
A notification says only that a question needs you, never the question. The phone app has settings of its own, including dictation if your relay was deployed with it.
If notifications don't arrive: open the app from its Home Screen icon rather than the browser, check that a Focus mode or low-power mode isn't holding them back, and remember that clearing the browser's data for the relay's site deletes the phone's keys, so it has to be paired again. So does moving the relay to another domain.
Run the Setup Check
Back in Connection, press Check setup on the Setup check row. It runs these steps in order and stops at the first that fails, naming it:
| Step | What it checks |
|---|---|
| Relay health and protocol | The relay answers and is claimed |
| Claim | The relay lists this computer as its owner, under the keys held here |
| Socket with a fresh ticket | A new connection to the relay opens |
| Push configuration | The relay has a push key, and holds a push subscription for at least one paired phone or tablet |
| Encrypted attachment round trip | A test question goes out with a test image, which comes back from the relay intact |
| Test question to your phones | Your answer reaches this computer and is typed into a terminal |
The test question, Daintree setup check: did this question reach you?, has one choice, Received. Answer it on your phone within five minutes. Your answer is typed into a diagnostic terminal shown in Connection, which runs no agent and no process, so nothing typed into it can run.
Keep Settings open until the check ends. Closing Settings cancels it, though switching to another Settings tab doesn't. Once a kit is verified and the check passes, Setup isn't finished goes away. Press Check again whenever you want to rerun it; a failed run makes setup unfinished again.
A pass proves one round trip at the moment it ran. It doesn't prove every notification will reach your lock screen.
Enroll Remote Hosts
If you use Remote Hosts, agents there can ask you questions too, and they ask and get their answers on the host itself, so they keep working while this computer sleeps. Setup still happens once, here. While Decisions is connected, Daintree enrolls each Remote Host you connect to as one of your devices, with keys the host makes itself and seals with its own keychain. A host that already has its own Decisions setup, or is enrolled with another relay, is left as it is.
Hosts have their own Remote Hosts section, beside the phones and tablets under Devices. Each host you've connected to or enrolled is listed once, with whether it's enrolled, an enrollment that failed, Enroll when that would do something, and Revoke while it holds a device.
- No keychain. A host without one, as a WSL distribution or a headless Linux machine usually is, isn't enrolled automatically. Its row offers Enroll with weaker storage…, which asks Use the weaker key storage on <host>? before keeping that host's keys under a fixed key. That applies to that host alone.
- Machines you don't own. Hosts you're already connected to are enrolled as soon as the relay connects, and the switch to stop that appears only once a relay is set up. Disconnect from those hosts before you connect the relay, or Revoke them afterwards, then turn off Enroll Remote Hosts automatically and enroll hosts one at a time with Enroll.
- What a host can read. An enrolled host can read your agents' questions and answers, as every paired device can, and it counts toward the twelve-device limit.
- Turning it off. Turning Decisions off here turns it off on each connected host straight away, and on any other host the next time this computer connects to it.
On Windows, the hosts are Linux distributions in WSL, which usually have no keychain, so they enroll with weaker storage. The trust model for hosts in general is on Remote Host Security.
Revoke a Device or Rotate Keys
| Action | Where | What it does |
|---|---|---|
| Revoke | On each phone or tablet under Devices, and each host under Remote Hosts | The relay stops accepting that device, and Daintree seals a new key to each device that remains, so the revoked one can't read new questions. A revoked host isn't enrolled automatically again. |
| Rotate keys | Under Encryption | Makes a new key without revoking anyone. |
Revoking can't reach into a device: questions, answers and screenshots already on it stay there. After either action, save and verify a new recovery kit, because the old one lacks the new key.