Obsync Community Edition

Free open self-hosted sync for your own VPS or NAS: a server, the Obsync plugin on every device, and one shared connection token. Obsidian is no longer tied to a single machine: notes, attachments, and version history stay available across your devices.

Quick start: a few Docker commands and a few settings inside Obsidian.

Open repository Choose managed Obsync

Requirements

Docker Engine or Docker Desktop.
Docker Compose.
Git.
HTTPS domain for sync outside a local network.

Server install

Clone the repository:

Open repository

git clone https://github.com/obsyncteam/obsync-ce.git
cd obsync-ce

Create .env:

cp .env.example .env

Set real random values. Do not leave secrets empty:

OBSYNC_POSTGRES_PASSWORD=<random PostgreSQL password, at least 16 characters>
OBSYNC_AUTH_TOKEN=<random token, at least 32 characters>
OBSYNC_PORT=4444
OBSYNC_STORAGE_QUOTA_BYTES=0
OBSYNC_ALLOWED_ORIGINS=

Start the server:

docker compose up -d --build

Check it:

docker compose ps
curl http://127.0.0.1:4444/ready

Expected ready response:

{
  "ok": true,
  "service": "obsync-server",
  "storage": {
    "metadata": "postgres",
    "blobs": "filesystem"
  }
}

Environment variables

compose.yml builds obsync-server:1.6.23 from ./server and starts PostgreSQL 16.

Variable	Required	Description
`OBSYNC_POSTGRES_PASSWORD`	yes	PostgreSQL password for the compose stack. Use a random value with at least 16 characters.
`OBSYNC_AUTH_TOKEN`	yes	Shared plugin token. Use a long random value.
`OBSYNC_PORT`	no	Host port bound to `127.0.0.1:4444`. Default is `4444`.
`OBSYNC_STORAGE_QUOTA_BYTES`	no	Vault quota in bytes. `0` disables the quota.
`OBSYNC_ALLOWED_ORIGINS`	no	Comma-separated origins for browser CORS access. CORS is closed by default.

S3 storage

Leave S3 variables empty to store files on the local server volume.

Variable	Description
`OBSYNC_S3_ENDPOINT`	S3-compatible endpoint, for example MinIO.
`OBSYNC_S3_REGION`	S3 region.
`OBSYNC_S3_BUCKET`	Bucket name.
`OBSYNC_S3_ACCESS_KEY_ID`	Access key.
`OBSYNC_S3_SECRET_ACCESS_KEY`	Secret key.
`OBSYNC_S3_FORCE_PATH_STYLE`	Use `true` for MinIO-style endpoints.

Data

Default Docker volumes:

postgres-data: PostgreSQL data.
obsync-data: synced file content and temporary uploads.

Back up both volumes.

Reverse proxy

For public or mobile access, proxy an HTTPS domain to the server.

Paths:

/health
/ready
/api/v1/
/sync

/sync must support WebSocket upgrade.

Example plugin URL:

https://sync.example.com

Do not use 127.0.0.1 on a phone.

Obsidian plugin

Plugin repository:

https://github.com/obsyncteam/obsync-plugin

Build from source

Build:

git clone https://github.com/obsyncteam/obsync-plugin.git
cd obsync-plugin
npm ci
npm run build

Install:

mkdir -p /path/to/vault/.obsidian/plugins/obsync
cp main.js manifest.json styles.css /path/to/vault/.obsidian/plugins/obsync/

Restart Obsidian or reload the app. Enable Obsync in Community plugins.

Plugin settings

Setting	Description
`Server URL`	Base URL of your sync server.
`Auth token`	The same value as `OBSYNC_AUTH_TOKEN`.
`Device name`	Visible label such as `pc`, `phone`, or `laptop`.
`Vault name`	Use the same vault name on every device.
`Sync attachments`	Sync binary files.
`Sync .obsidian`	Sync Obsidian configuration. Keep it disabled until note sync is verified.
`Max file size`	Files larger than this value are skipped.

First device

Start with the device that already has the source vault content.

Settings:

Server URL: https://sync.example.com
Auth token: OBSYNC_AUTH_TOKEN value
Device name: pc
Vault name: my-vault
Sync attachments: on
Sync .obsidian: off

Press Sync. Wait for the first indexing run to finish.

Additional devices

Use an empty or test vault.

Settings:

Server URL: https://sync.example.com
Auth token: OBSYNC_AUTH_TOKEN value
Device name: phone
Vault name: the same vault name as on the first device
Sync attachments: on

Press Sync. Wait for the first download to finish.

Version history

Open note history shows Markdown versions saved by the server.

For Markdown conflicts, Obsync leaves the local note unchanged. Open history, compare versions, and restore the one you need. Binary conflicts may create conflict copies.

Update

git pull
docker compose up -d --build

Safety

Back up the vault before the first sync.
Verify note and attachment sync before enabling .obsidian sync.
Use the same Vault name on every device.

License

Obsync Community Edition is distributed under AGPL-3.0-only.

The full license text is in LICENSE.

You can:

run Obsync Community Edition on your own server;
use it to sync Obsidian vaults;
read and modify the source code;
redistribute copies;
publish modified versions under the same license.

Obsync includes a server component. AGPL-3.0-only has network-use requirements.

If you modify the server and provide network access to the modified version, service users must be able to receive the corresponding source code under AGPL terms.

Third-party dependency licenses are listed in the package manager files included in the repository.