Vault client sync documentation

Feature name

Bitwarden sync documentation

Feature function

Get a better understanding on how sync between clients and vault happens.
Documentation at Sync your Vault | Bitwarden Help & Support is pretty incomplete.
You should ad more information on how sync works.

  1. Is there a push sync request from the server to clients (mobile, browser plugins, desktop) they will obey and download updated content (new, modified, deleted)?
  2. After login what is the time interval clients refresh the database? Indicate times specifically for each client type.
  3. How does update work? If I modify two different records from two different two different clients, is it possibile to damage the central database of the vault?
  4. Same as questìon number 3 but consider two different clients updating the same item? Could it bring the database in an unstable state? Is there some sort of protection/locking for records in the database?

@tgreer I see there is a lot of confusion (read complaining) about vault synching in the forums.
Can someone of the team please shed some light on how synching between each client really works please?

@blackph0en1x - l’ll work with our tech writer to see if we can make some additions.

1 Like

Perhaps this write up will help to better understand how sync works.

As I understand it, the encrypted database of your passwords is save on the Bitwarden server (cloud service, or self-hosted) the client then pulls a copy of the encrypted vault on login, and decrypts the vault when it’s open.
When a client updates a record or creates a new one this change is pushed to the server and all other clients will update either on the next sync, or immediately with the use of Websockets, or push notifications for mobile.

In the past few days I’ve been taking advantage of the “reused password” feature of my self hosted bw instance. I can tell that from whatever client (browser plugin, web vault, mobile) the other clients were not updated if I didn’t update them manually so there is surely no push or it is not working for me.
By the way thank you for the link.
@tgreer (sorry to bother you everytime :- ) is Live Sync really how clients sync?

@blackph0en1x it’s why I’m here :wink:

Live sync is indeed how syncing works. But of course, there is more to it. The elevator explanation is:

  • Web Vault is the system of record (why most functions are performed there)
  • All clients must be online to add new items/edit existing items
  • When a change is made, a comparison of the item timestamp is done, if the item in the vault is older than the item on the server, sync is required before edits can be made (don’t want to edit old stuff!)
  • When a change takes place, it’s encrypted at the device and sent to the server
  • The server gets the update, and then uses WebSockets to push updates to the Desktop and Browser extension, and then push notifications are sent to the mobile apps to tell them to sync the new data.

Very high-level, but hopefully that clears up most confusion. I’ll still get in touch with @fre

1 Like

Thank you for the explanation @tgreer but this still doesn’t explain why clients do not update until there is a manual update.
I’ve tried the following:

  1. logout from all clients
  2. login in to Chrome plugin
  3. update a note for an item
  4. immediately login to webvault —> note was updated
  5. immediately login to desktop app (macos) —> note was updated
  6. update note a second time
  7. check item on already logged in webvault after more than 5 minutes —> note was NOT updated
  8. check item on already logged in desktop app (macos) after more than 5 minutes —> note was NOT updated
  9. manually synchronize vault from the desktop app (macos) —> note was NOT updated neither on desktop app and web vault
  10. manually synchronize Chrome plugin —> webvault was updated, desktop app (macos) was NOT updated;
  11. manually synchronize desktop app (macos) —> note was not updated [this really surprised me!! how is this possible after I synchronized the Chrome plugin with which I modified the note the second time?]
  12. disconnected from desktop app (macos)
  13. full login with 2FA to desktop app (macos) —> note was updated

From my little test, push notifications seem not to work or I still don’t understand how they work. I am really lost :sweat_smile:

If you want to make more tests let me know will be more than happy to help.

@blackph0en1x thanks for the detail!

Couple of quick notes:

  1. When logging in, a fresh vault download is occurring.
  2. Web Vault doesn’t refresh on the page, you’d need to navigate to another view or manually refresh the site.
  3. The sync feature just downloads an updated item from the web vault/server - it doesn’t force a sync on other clients.
  4. Items that are edited are always updated on the server and web vault (it is the system of record), you may just need to refresh the web vault to see the updates.

As to why your clients aren’t syncing, I believe you need to be able to connect to for the signalr (websocket) servers to sync, and of course you’ll need push notifications working on your mobile devices (note that F-Droid doesn’t support live sync, since it doesn’t support google play services and firebase push notifications)