Set Up Obsidian LiveSync with Managed CouchDB

Obsidian Self-hosted LiveSync can use CouchDB as the shared endpoint between your devices. Each device keeps its vault locally; the remote database carries synchronization data between them. Hosting that endpoint on Layerbase Cloud removes the server installation, public certificate, and operating-system maintenance from your setup.

CouchDB requires Layerbase Pro. The Pro plan is $15 per month. CouchDB is not included in Free or Solo. Check pricing before starting. If all you need is one small personal vault and you already maintain a server, self-hosting may be more economical. This guide is for people who prefer a managed CouchDB endpoint.

We will connect a new test vault first, add a second device, and check that an edit survives a disconnected session. Move real notes only after that works.

What you need

• A Layerbase Pro account and a new CouchDB instance dedicated to this setup.
• Obsidian on two devices, with permission to install community plugins.
• A password manager for database credentials and encryption passphrases.
• A separate backup of any vault you intend to migrate.

LiveSync is a community plugin, separate from the official Obsidian Sync service. It also supports other remote types; this guide specifically covers CouchDB. The project's documentation describes those alternatives.

Use an empty test vault outside iCloud, Dropbox, or any other synced folder. Do not have another synchronization service writing to that same vault. An ordinary backup that copies files elsewhere is different from two services both trying to reconcile changes.

1. Create the managed endpoint

Create a CouchDB instance and open its Quick Connect details. Save the generated HTTPS endpoint and administrator credentials privately.

Separate the connection into these parts:

Use the hostname actually supplied by Quick Connect. Do not copy the example hostname, include /_utils, or append the database name to the server URL when the client asks for it separately. If Quick Connect includes credentials in the URL, transfer them into the separate credential fields rather than leaving them embedded in a shareable URL.

The Layerbase instance and a CouchDB database inside it are different things. We will create obsidian_vault inside the instance; it does not need to have the same name as the Layerbase resource.

2. Prepare CouchDB through Fauxton

Open /_utils/ on your generated HTTPS hostname and sign in with the administrator credentials. Fauxton is CouchDB's administration interface.

Create a non-partitioned database named obsidian_vault. Use a fresh database for the test; do not point initial setup at existing application data.

In Fauxton's configuration editor, set these values for CouchDB 3.2 and later. A fresh instance ships with require_valid_user off, so expect to add most of this rather than confirm it. These are instance-wide settings, which is why this guide starts with an instance dedicated to LiveSync:

For older CouchDB 3.0-3.1 installations, require_valid_user belongs in couch_httpd_auth and enable_cors belongs in httpd. Do not add require_valid_user under chttpd_auth; it is not the setting used for this check. See the authentication configuration reference.

CORS allows these client origins to make browser-style requests; it does not give them permission to read your database. Keep authentication and database permissions in place. On an instance already serving another app, preserve its required origins rather than replacing the list. CouchDB CORS configuration

LiveSync's provisioning utility also configures request and document limits. Its current values are 4294967296 for chttpd/max_http_request_size and 50000000 for couchdb/max_document_size. Review those only if the plugin's requirements check or a payload-size error calls for them: larger limits do not override limits in a hosting proxy, and they are not a promise that a large attachment will sync successfully.

Do not run a generic server-installation script against the managed endpoint. Cluster setup, listener ports, and bind addresses are already managed. If a required setting is unavailable, contact support with the setting name and error, leaving out credentials.

3. Give your devices a database-scoped account

Use the server administrator for setup, then use a regular CouchDB user for device synchronization.

In Fauxton, open the _users database. If it is not listed, create a non-partitioned database named _users first, as the administrator. Create the following document inside it, substituting a unique password before saving:

{
  "_id": "org.couchdb.user:obsidian_sync",
  "name": "obsidian_sync",
  "type": "user",
  "roles": [],
  "password": "REPLACE_WITH_A_UNIQUE_PASSWORD"
}

Open the permissions for obsidian_vault. Add obsidian_sync to the database's member names. Keep administrator access restricted; do not give this user the _admin role. The intended _security document is:

{
  "admins": { "names": [], "roles": ["_admin"] },
  "members": { "names": ["obsidian_sync"], "roles": [] }
}

Members can read and write ordinary documents in this database. They cannot administer the whole server. That is enough for document replication against a database an administrator has already created. CouchDB database permissions

Before adding personal notes, verify that an unauthenticated request to /obsidian_vault/_all_docs is rejected. Test from a signed-out client, since your Fauxton session is already authenticated.

4. Connect the first vault

Install Self-hosted LiveSync in an empty test vault and enable it. The plugin offers to start setup straight away. You can also reach it later from the plugin's settings under Quick Setup, which lists "Connect with Setup URI", "Rerun Onboarding Wizard", and "Enable LiveSync".

In the wizard, choose "I am setting this up for the first time", then "Configure a remote manually" on the Connection Method step. Enable end-to-end encryption and save its passphrase. Encryption covers file contents, not file names: paths stay readable on the server unless you also turn on "Obfuscate Properties". Select CouchDB as the remote type, then enter the endpoint, database name, and credentials. Follow the manual onboarding guide for your plugin version.

Use the server administrator for this first device, not obsidian_sync. The wizard's last step, "Final Confirmation: Overwrite Server Data with This Device's Files", deletes obsidian_vault on the server and rebuilds it from this device. Only a server administrator may delete a database, so the step fails on a member account with 401 and "You are not a server admin", and the wizard comes back to it after every restart. There is no non-destructive route through this branch of the wizard; the only choice under its Advanced section is "Use this device's settings".

Recreating the database also replaces its _security document with an administrator-only one, so obsidian_sync starts getting 403. Re-apply the document from step 3 as administrator, then check that the regular account can read /obsidian_vault/_all_docs again and that an unauthenticated request still cannot.

Now move this device onto the regular account. In the plugin's Remote Configuration, open the saved connection, replace the username and password with the obsidian_sync credentials, and use "Test connection and save". Later devices never need the administrator: they join an existing setup instead of initializing one.

The wizard leaves synchronization switched off. Open Sync Settings, choose LiveSync under Synchronization Preset, and click Apply. The Quick Setup "Enable LiveSync" link does the same thing. Nothing replicates until one of them is done.

Two dialogs show up around this point and neither is a failure. "Synchronisation paused for compatibility review" appears after the database is rebuilt; click "Resume synchronisation". "Self-hosted LiveSync Config Doctor" offers to walk through configuration suggestions, and answering "No" leaves synchronization working.

Once the device is on the regular account, "Check server requirements" reports "2 issue(s) detected" and "Access forbidden". That is the check itself needing administrator access, not a sync failure. Run it with the administrator credentials when you want its output, and keep the regular account on your devices.

Create sync-check.md and wait for upload to finish.

5. Add the second device

Generate an encrypted Setup URI from the working first device. On device two, install LiveSync in an empty vault, choose "I am adding a device to an existing synchronisation setup", import that URI, test the settings, and restart to fetch remote data. After the fetch, open Sync Settings and confirm a preset is active: with plugin 1.0.29 the imported settings arrived with every automatic sync trigger off, so device two only synced on "Sync now" until the LiveSync preset was applied there too. Verify the test note, then edit it and check device one. Second-device walkthrough

The URI contains credentials. Protect it and keep its passphrase separately. That passphrase differs from the vault-encryption key; retain both outside the vault.

6. Verify the behavior you will rely on

Before migrating, complete this small acceptance check:

On conflicting edits the plugin offers "Use Base", "Use Conflicted", and "Concat both". The first two take one side and are the clean choices. "Concat both" splices the two versions together at word level, which rarely produces what either device meant, so treat it as a last resort and repair the result by hand.

Do not assume that successfully opening the database's home page proves all of these. A basic HTTP check does not exercise attachments, conflicting edits, or reconnect behavior.

For frequent synchronization, consider pinning the instance always-on within your Pro pool. Hibernation can add a delay to the first connection, and ongoing replication activity can prevent an instance from becoming idle. Pinning changes availability behavior, not the subscription price. Check your pool capacity in the dashboard before enabling it.

Troubleshooting

Sync and recovery are separate tasks

Replication can carry an accidental deletion to every connected device. Keep an independent vault backup and practice restoring it into a separate vault before you need it.

For hosted database backups, also verify how to restore into a separate target without immediately reconnecting clients that might replay unwanted changes. Preserve the encryption passphrase outside the database: restoring encrypted data does not recover a lost key.

Enable optional settings or hidden-file synchronization only after ordinary notes work. Introduce one feature at a time and repeat the two-device check so it is clear which change caused a problem.

Is managed CouchDB the right choice?

This setup is useful if you specifically want LiveSync with CouchDB and prefer paying for managed infrastructure to maintaining a server. It is less compelling if you already have a well-maintained server or want a sync product with no database configuration at all.

Start with the test vault, verify the workflow, and then decide whether the convenience warrants the subscription. Create a managed CouchDB endpoint, or read how CouchDB replication and conflicts work before connecting real notes.

If you are building your own application rather than syncing Obsidian, the PouchDB and CouchDB tutorial builds the client-side workflow directly.