Sync your machines

On this page

Sync is off until you turn it on. When it is on, each machine pushes encrypted changes to a bucket you own and pulls the changes of your other machines. There is no notegraph server in the middle.

You can run notegraph sync yourself to push and pull once. There is no background sync in this version, and serve has no --sync option.

Set up a bucket#

Any S3-compatible bucket works. This example uses Cloudflare R2.

  1. Make a bucket, for example notegraph-vault. Use a bucket that holds nothing else.
  2. Make an API token for that one bucket only. Give it read, write, list and delete on the bucket (in R2, Object Read & Write on the specific bucket). Do not use an account-wide token.
  3. Copy the access key ID, the secret access key and the S3 endpoint. For R2 the endpoint is https://<account-id>.r2.cloudflarestorage.com.

A token for one bucket limits the damage if it leaks. Whoever has it can delete the objects in that bucket and run up your costs, but cannot reach anything else in your account.

Turn on sync#

notegraph sync setup --endpoint https://<account-id>.r2.cloudflarestorage.com --bucket notegraph-vault

--region defaults to auto. The endpoint must be https. Setup does this, in order:

  1. Asks for the access key ID and the secret access key. Nothing you type shows on screen.
  2. Checks that the bucket answers and that the keys sign.
  3. Makes the vault key and shows the recovery phrase of 24 words.
  4. Asks you for three of the words, to prove you wrote them down.
  5. Saves the keys in the OS keychain, then pushes your notes. Until the words match, nothing is saved and nothing is pushed.

sync setup needs a terminal. It refuses to run inside an agent shell, because it handles your keys. Your keys must not reach an agent.

Keep the recovery phrase#

The phrase is the root key of the vault. Anyone who has it and can read your bucket can read every note in it.

Pair a device#

  1. On a device that already syncs, run notegraph pair --show. It shows a one-time code.
  2. On the new device, run notegraph pair and type the code. Nothing you type shows on screen.
  3. The new device shows the vault ID, the bucket host and the device names. If they are yours, press y.

The code shows on its own screen and never stays in your scrollback. It expires after 10 minutes. After that, it opens nothing. Whoever has the code before it expires can join your vault, so show it only on your own screen. When the new device has joined, it pulls the vault and prints Paired. There is no QR code in this version.

Recover with the phrase#

When no other device is at hand, for example after you lost your only machine:

notegraph pair --recover

It asks for the bucket endpoint, the bucket name, the region, the vault ID, the key epoch (1 unless you rotated the keys), the access key ID, the secret access key and the 24 words. Nothing secret shows on screen.

Recovery brings back your notes and their history. It does not bring back attachments, because they are not in the bucket in this version.

What the bucket sees#

The bucket holds ciphertext. The provider cannot read your notes, their paths, their titles or your history. The provider can see the vault ID, the device IDs, how many objects there are, their sizes, when they were uploaded, and the IP address each device connects from. Note paths and titles are never in an object name.

Sync warnings#

notegraph sync prints a line for each device whose changes it could not take in full. notegraph status shows the sync state, the queue and one row for each device. A run with any such device exits with status 3, and sync --json reports partial.

held_back#

Device 1a2b3c4d: held_back. The bucket lists fewer batches than another device saw. Objects that you had seen are gone from the bucket, or the bucket went back to an older state. notegraph prints a warning and keeps going. The log header shows sync held back. Look in the bucket for a lifecycle rule, a restore or a delete. Do not delete anything else until you know why.

rejected: decrypt_failed and bad_update#

decrypt_failed means a batch did not open with this vault's key. bad_update means a batch broke a rule of the format. notegraph does not apply the batch, and does not apply the ones after it from that device. A damaged object can cause this, and so can something that wrote to your bucket and is not notegraph. Check who can write to the bucket, and replace the token (see If you lose a device). If another device rotated the keys, this device must pair again.

Ignored prefix#

Ignored 1a2b3c4d: no valid device record. A folder in the bucket looks like a device but has no record that opens with this vault's key. notegraph reads nothing from it. If you do not know that device, check who can write to the bucket.

Other results: gap (a batch is missing, later ones wait) and bucket_error (a batch could not be read, often a network problem). Run notegraph sync again later. The sync state in the header of the log view is one of sync off, sync <age> ago, sync offline, sync key missing, sync held back and sync error.

Keys on Linux without a secret store#

notegraph keeps your root key and your bucket keys in the OS keychain. A machine with no keychain, such as a Linux server with no desktop session, cannot do that. Setup then asks whether to keep them in secrets.key in the data directory, a file that only you can read. If you answer no, nothing is written. You can also opt in by putting secret_store = "file" under [sync] in config.toml.

The file goes into every backup of your home folder, and any program that runs as you can read it. Prefer a keychain. notegraph status and notegraph sync warn while the keys are in a file.

Costs#

Providers charge for requests and for storage. notegraph has no pricing to show you, and this page gives no price until someone measures a real vault. What the code does, counted from the source, per run of notegraph sync:

So a run with nothing new sends about 3 requests, plus 3 for each other device. The count grows with how often you run notegraph sync and with the number of devices. notegraph deletes no batches during normal sync, so storage only grows. notegraph sync rotate --delete-old deletes the objects of an old key epoch.

If you lose a device#

A lost laptop holds your notes, your history, your keys and your bucket token. Do these four steps, in this order:

  1. At your bucket provider, make a new token for the bucket and revoke the old one.
  2. On each remaining device, run notegraph sync credentials and type the new keys.
  3. On one remaining device, run notegraph sync rotate. It makes a new root key and a new recovery phrase, and pushes your vault under it. Write the new phrase on paper and destroy the old paper. It then asks whether to delete the objects of the old key from the bucket. The old key opens them until you do. If you answer no, run notegraph sync rotate --delete-old later.
  4. On each other remaining device, run notegraph pair with a code from the device that rotated (notegraph pair --show).

Content that the lost device already had stays exposed. The new key protects what you write from now on, not what the thief already holds. Turn on full-disk encryption on every machine that holds a vault, so that a lost machine is locked. If you pasted a token or a password into a note, read rotate a pasted credential.