Skip to content
FUTO Notes

FUTO Notes sync password: where it's stored and how to change it

The sync password does two jobs with one string: it signs the app in to your server, and it unlocks the vault key that encrypts your notes. Because both jobs use the same password, the server’s configured password and the password protecting your notes have to stay the same. Changing it means starting a new vault on the server, and the steps are below.

What the sync password does

  • Sign-in. The app sends it to your server, which checks it against FUTO_NOTES_PASSWORD (or FUTO_NOTES_PASSWORD_HASH) from its .env and returns a session token.
  • Unlocking. The app runs it through PBKDF2 to decrypt the vault key stored on the server. See how the encryption works.

The first device to connect to an empty server creates the vault key and wraps it with the password it signed in with, which is the server’s password. From then on the two are tied together.

Use a long random password or passphrase. Anyone who gets a copy of the server’s data directory can try to guess it offline, and it is the only thing between that copy and your notes.

Where the app stores it

Each app saves the password after a successful connect, so it can reconnect without asking. It is never written to a file in plain text.

PlatformWhereScope
Desktop (Linux, macOS, Windows)The OS keyring: Secret Service on Linux, Keychain on macOS, Credential Manager on Windows, under the service name FUTO Notes E2EE syncOne entry per notes folder path
iOSThe Keychain, readable only while the device is unlockedOne per app
AndroidApp preferences, encrypted with a non-exportable Android Keystore keyOne per app

The vault key is not stored anywhere. The app derives it again from the password each time it connects.

When the desktop keyring is unavailable

Without a keyring, the desktop app still connects, but it keeps the password only in memory until you quit. This happens, for example, on a Linux system with no Secret Service running. After a restart, Settings → Sync shows a Vault password field with the placeholder “Required after restart”. Enter the password and press Sync now. The app does not fall back to saving it in a file.

Forget the saved password (desktop)

Settings → Sync → Forget password removes the saved copy from the keyring. The current session keeps working, and the app asks for the password again after the next restart.

Disconnect a device

On desktop, Settings → Sync → Reset connection. On iOS and Android, Settings → Self-hosted sync → Disconnect. Either one removes the saved password and this device’s sync state. Your notes stay on the device.

If you lose the sync password

Your notes on each device are unaffected. They are plain markdown files, and only sync stops.

Look for the password in two places first:

  • The server’s .env file, on the FUTO_NOTES_PASSWORD= line, unless you replaced it with a hash.
  • On desktop, the OS keyring entry for FUTO Notes E2EE sync (Keychain Access on macOS, a Secret Service viewer such as Passwords and Keys on GNOME, Credential Manager on Windows).

If it is gone, the copy on the server cannot be decrypted, by you or by anyone else. There is no reset or recovery key. Set up a new vault with a new password using the steps below, and your devices upload their notes again. Anything that existed only on the server is lost.

Changing the sync password

Why changing FUTO_NOTES_PASSWORD alone doesn’t work

The server’s password only controls sign-in. The vault key stays wrapped under the old password, and nothing in the FUTO Notes apps can re-wrap it under a new one. If you edit FUTO_NOTES_PASSWORD and restart the server:

  • A desktop app that is already signed in keeps syncing on its existing session, for up to seven days. Changing the password does not end sessions.
  • Once that session expires, and the next time the iOS or Android app starts, signing in with the old password fails.
  • Entering the new password gets further: sign-in succeeds, but the app cannot decrypt the vault key, because it is still wrapped under the old password. The app reports a connect or sync failure.

Nothing is deleted. Putting the old password back in .env and running docker compose up -d again makes sync work again.

Warning: Don’t change the server’s password on its own. If you already did and a device can no longer sync, put the old password back. Don’t use Full reset to fix it: Full reset permanently deletes every note on that device, and the new password still won’t open the vault.

Change the password safely

The supported way is to start a new vault: set the old server data aside, set the new password, and let a device upload everything again. These steps are for the Docker install; the commands run from your install directory.

  1. Sync every device and let each one finish. Choose the device with the most complete set of notes; it will become the source for the new vault.

  2. Disconnect every device. On desktop, Settings → Sync → Reset connection. On iOS and Android, Settings → Self-hosted sync → Disconnect. Notes stay on each device.

  3. Set the old data aside and change the password. Run these commands from your install directory, in the same shell:

    1. Set DATA_DIR to the full FUTO_NOTES_DATA_DIR path in .env. For a default install, run DATA_DIR='/home/you/futo-notes/futo-notes-data', replacing you with your username. If you chose a different install or data directory, use that path instead.
    2. Check whether a directory named $DATA_DIR.old already exists. Move it aside before continuing, so the old data does not get nested inside a previous backup.
    3. Stop the server with docker compose down. Move the old data with mv -- "$DATA_DIR" "$DATA_DIR.old", then create an empty directory with mkdir -- "$DATA_DIR".
    4. Edit .env and set FUTO_NOTES_PASSWORD to the new password. If you use FUTO_NOTES_PASSWORD_HASH instead, replace the hash with one made from the new password using the hash generator.
    5. Start the server with docker compose up -d, then run docker compose ps and wait for it to show the server as healthy. Use up -d, not restart: a restart keeps the old environment.

  4. Connect the source device with the new password. It creates a new vault key, wraps it with the new password, and uploads every note and image.

  5. Connect the other devices with the new password. A note that matches the server’s copy is matched up with it. Where a device’s copy differs, the device moves its own version to a conflict copy and takes the server’s version under the original name. Notes that exist only on that device are uploaded. A note you deleted on one device but that still exists on another comes back when that other device connects, so delete it again. See sync conflicts.

  6. Delete the old data once everything is back. The directory at $DATA_DIR.old, and any backup of it, can still be decrypted with the old password. If you are changing the password because the old one leaked, delete them.

If you run a release binary instead of Docker, the steps are the same: stop the service, move the SQLite database and the blob directory aside together, set the new password in the environment file, and start it. Move both. The server refuses to create a new database next to a blob directory that still holds blobs.

Changing the password this way does not make old copies unreadable. Anyone who has the old password and an old copy of the server’s data can still read that copy. The new vault has a new vault key, so the old password does not open it.

The server’s API does accept replacement key material, so a tool could re-wrap the existing vault key without starting over. No FUTO Notes app or tool does this today. See the sync API.

Next steps