Skip to content
Get packs

Guide · Open source

How to use obsidian-livesync: setup, sync and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

Self-hosted LiveSync is a community-developed Obsidian plug-in that keeps your vault in sync across devices using infrastructure you control. This guide explains the options it supports, how to get a first device and a second device syncing, and what to watch out for. By the end you will know which backend fits your setup and how to test that sync works in both directions.

Self-hosted LiveSyncvrtmrz/obsidian-livesync · ★ 12.9k · MIT

Quick start

  1. 1Pick a backend. Choose CouchDB, S3-compatible object storage, or peer-to-peer WebRTC based on what you can run and maintain.
  2. 2Set up the server or signalling relay. Follow the linked guide for your backend. Peer-to-peer can use the project's public signalling relay.
  3. 3Install the plug-in on device one. Install and configure Self-hosted LiveSync using Quick Setup, Object Storage Setup, or Peer-to-Peer Setup.
  4. 4Generate a Setup URI. From the working device, generate a Setup URI to reuse on other devices.
  5. 5Add your other devices. Follow the same guide on each device using the Setup URI.
  6. 6Test in both directions. Create test notes on each device and confirm they appear everywhere.

What you need before you start

Self-hosted LiveSync stores data on a server you set up and maintain, or syncs devices directly with WebRTC. The README says you must set up and keep your own server secure. Choose one of three routes: CouchDB, object storage, or peer-to-peer.

  • CouchDB: a CouchDB-compatible server.
  • Object storage: an S3-compatible service or server, such as MinIO, S3 or R2.
  • Peer-to-peer: nothing to host for data, but a signalling relay is still needed for peer discovery. The project's public signalling relay can be used.
  • Obsidian 1.7.2 or later for Self-hosted LiveSync 1.0.

Choose a server setup guide

For CouchDB, the README links several guides depending on where you want the database to run. The linked guides explain setup and any provider-specific costs. A community-run managed CouchDB option is also listed, but it is operated by a third party, not by the project.

  • Your own server: run CouchDB on a Raspberry Pi or another server you manage (docs/setup_own_server.md).
  • Docker: deploy CouchDB with the supplied Docker stack (docker/README.md).
  • Fly.io: manage your own CouchDB instance on hosted infrastructure (docs/setup_flyio.md).
  • IBM Cloudant (managed): a database service managed by IBM (docs/setup_cloudant.md).

Install the plug-in and connect your first device

Install and configure Self-hosted LiveSync on your first device using the Quick Setup guide for CouchDB, the Object Storage Setup guide, or the Peer-to-Peer Setup guide. The README's install command is a git clone of the repository; the plug-in itself is set up through the guides above.

Back up your vault before installing or upgrading the plug-in, as the README advises.

  • Do not run this plug-in alongside another sync solution, including iCloud and Obsidian Sync.
git clone https://github.com/vrtmrz/obsidian-livesync

Add your other devices with a Setup URI

Once the first device works, generate a Setup URI from it and follow the same guide to add your other devices. This avoids re-entering server details on each device.

For a faster and simpler initial replication when setting up later devices, the README points to the Fast Setup Guide.

Test sync and read the status bar

Create test notes and confirm that they synchronise in both directions. Synchronisation status appears in the status bar and inside the editor by default.

The main indicators are a stopped icon, a starting icon, a waiting icon in LiveSync mode, an in-progress icon, a history-comparison icon, and an error icon. Arrows show uploaded and downloaded chunks and metadata. Allow pending file operations to finish before closing Obsidian, especially after deleting or renaming files.

  • Stopped: sync is not running.
  • In progress: synchronisation is under way.
  • Error: an error occurred; check the troubleshooting guide.
  • Arrows: uploaded (up) and downloaded (down) chunks and metadata.

Troubleshoot problems and recover safely

If Obsidian or LiveSync cannot start normally, use Recovery and flag files before changing or resetting a remote database. The general troubleshooting page is docs/troubleshooting.md.

Configure Hidden File Sync only after ordinary note synchronisation works. Settings, snippets, themes and plug-ins can be synced through Customisation Sync (Advanced) or Hidden File Sync.

  • Start with normal note sync before enabling Hidden File Sync.
  • Check recovery notes before resetting a remote database.

What people use it for

  • Keeping a personal vault on a self-managed CouchDB server on a Raspberry Pi.
  • Syncing notes between two devices directly over WebRTC without a central data store.
  • Keeping research or engineering notes on infrastructure a team controls for privacy reasons.
  • Using S3-compatible object storage such as MinIO, S3 or R2 as the sync backend.

Frequently asked questions

Is obsidian-livesync free?

The project is licensed under the MIT License. The README notes that linked setup guides explain any provider-specific costs, so hosting costs depend on the server you choose.

What do I need to run obsidian-livesync?

You need Obsidian 1.7.2 or later for version 1.0, plus one backend: a CouchDB-compatible server, S3-compatible storage, or two devices for peer-to-peer. You must set up and maintain your own server.

Is obsidian-livesync compatible with Obsidian Sync?

No. The README says the plug-in is not compatible with the official Obsidian Sync and cannot synchronise with it. It also should not run alongside iCloud or other sync solutions.

Does obsidian-livesync support end-to-end encryption?

Yes, the features list says it supports end-to-end encryption for synced notes. Check the setup guide for your backend for how to enable it.

Do I need a server for peer-to-peer sync?

Peer-to-peer does not need a central data-storage server, but a signalling relay is still required for peer discovery. You can use the project's public signalling relay, and at least one device with the data must be online while another syncs.

What should I do if sync is not working?

Read the Tips and Troubleshooting page, and use Recovery and flag files before changing or resetting a remote database. Back up your vault first.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Obsidian-livesync suits users who want their notes on a server or devices they control and are comfortable setting up CouchDB, object storage or a signalling relay. If you want zero setup, want to combine it with Obsidian Sync or iCloud, or need a supported hosted service, consider a hosted option or a tool such as Syncthing, Remotely Save or Obsidian Sync instead.

Install options & downloads