Appearance
What Halcyon Sync is
Halcyon Sync keeps one vault's notes in step across your Macs, end-to-end encrypted. You turn it on a vault at a time, and vaults you don't turn it on for stay exactly where they are.
Important
Sync is in limited testing, and not every build has it. If Settings has no Sync tab, you have a build without it rather than a broken one. Nothing on this page applies to that build, and everything else in Halcyon works exactly the same either way.
Everything else in the app needs no account. Nothing outside this section of the documentation asks who you are, and a local vault never will.
For what a Halcyon account costs and what it includes, see halcyonnotes.com.
What it actually does
The vault on disk is the truth on your Mac. The server holds an encrypted copy of that folder, and sync's only job is to make the two agree, in both directions.
That has a consequence worth knowing: a sync that can't finish stops rather than reaching for your notes. Nothing ever rearranges your vault to make sync work. It catches up, or it waits.
A change from your other Mac lands as an ordinary edit to the file, so the note list, the open editor and the unsaved-changes warning all behave exactly as they do when you edit the vault in Neovim. There's one set of behaviours to learn, not two.
What syncs
Only .md files. Anything else in the folder stays on the Mac it's on: images, PDFs, whatever else lives beside your notes.
Deletes travel like edits. A note you trash on one Mac goes to the macOS Trash on the other, where Put Back still works.
Pins don't travel. They're device-local. See Notes and folders.
What the server can see
Never your notes. Contents, paths, filenames and titles are encrypted on your Mac before they leave it, under keys that never leave your Keychain. There's no key on the server side that opens them.
It does see the shape of the vault:
| The server knows | The server does not know |
|---|---|
| The name you gave the vault | Any note's title, filename or path |
| How many files there are | What any of them say |
| How big each encrypted file is | |
| When each one changed | |
| Which file became which in a rename | |
| Which files conflicted |
The vault's name is the one thing stored as you typed it, because it's how the website and the vault picker on your other Mac list it. The app says so at the moment you type it.
The server can tell when your two Macs mean the same file, without knowing which file that is. It learns the shape of your vault and nothing about what's in it, and both halves of that are true.
Warning
End-to-end encryption has a cost, and it's a real one: if you lose every Mac that holds the account key and never set a recovery code, the remote copy is gone for good. Nothing on the server can unwrap it. This is the same bargain FileVault and Signal make.
The recovery code is how you buy insurance against that. It's offered once, when you turn sync on, and Settings will set one later.
Where to go next
- Turning it on: signing in, activating a vault, the recovery code.
- Adding another Mac: the six-digit handoff.
- Versions and conflicts: what happens when two Macs edit one note.
- When Sync goes wrong: reading the status line.