Pkv Sync
Self-hosted, Git-native Obsidian vault sync with a built-in MCP server, search, and wiki lint.
PKV Sync is a self-hosted, Git-native sync server for Obsidian vaults.
The name is PKV Sync: PKV is the initialism of Personal Knowledge Vault, and Sync is spelled out in full.
Document version: v1.10.2.
English · 简体中文 · 繁體中文 · 日本語 · 한국어
Status
PKV Sync 1.10.2 ships its MCP Registry metadata under the canonical
GitHub namespace case (io.github.CyberKurry/pkv-sync), which is the name
the registry's OCI ownership check compares against. The product content
matches 1.10.1: an edit made while a pull is downloading a file becomes a
visible conflict instead of being pushed over the other device's committed
version; a file the server refuses is reported on every pass instead of
turning the status bar green, and one per-file rejection no longer wedges
the rest of the vault; moving a note with a non-ASCII name keeps its
Markdown links intact; and an interrupted self-update restores the previous
plugin build. Upgrade the server and plugin together.
Features
Sync
- Multi-user, multi-vault sync over authenticated devices, with per-vault push locks and idempotent retries.
- Real-time push. Small edits land sub-second over Server-Sent Events; polling stays as a safety net.
- Git is the source of truth. Every vault is a bare git repo, so per-file history, unified diff, and single-file restore work out of the box — in the plugin and in the admin panel.
- Conflict-safe. The plugin never silently overwrites local edits;
conflicts surface as
.conflict-*files with a one-click resolver.
Operate
- Admin panel in five languages (English, 简中, 繁中, 日本語, 한국어) for users, device tokens, vaults, invites, activity, and blob GC, with confirmation dialogs for destructive vault and user actions.
- AI-readable vaults. MCP exposes read/write tools over stdio or the
embedded
/mcproute onpkvsyncd serve(default on), and a ready-to-use MCP Registry entry ships with every release (io.github.CyberKurry/pkv-sync). - Built for LLM-maintained wikis. Beyond reading and writing, an agent can search by frontmatter, page through results exactly, lint a layer's links, find the pages whose sources went stale, and write behind a dry run plus content-hash guards — see the LLM Wiki workflow.
- Bounded by default. Admin-created passwords follow the setup-grade strong policy, token secrets are shown exactly once, uploads and MCP responses are size-capped, and live SSE streams revalidate revoked tokens.
Design
- Mature technology, on purpose. Single binary, single SQLite metadata DB, one bare git repo per vault, one content-addressed blob per attachment.
Quick start with Docker Compose
The recommended path. Caddy in deploy/caddy/ fronts HTTPS via Let's
Encrypt; PKV Sync sits on 127.0.0.1:6710 inside the compose network and
never sees plain HTTP from the public internet.
You need a domain name (e.g. sync.example.com) with A/AAAA records
pointing at the server, and ports 80 and 443 reachable from the
internet (port 80 is needed for ACME HTTP-01 validation).
Set up the stack
Generate a deployment key:
docker run --rm ghcr.io/cyberkurry/pkv-sync:latest genkeyDrop
config.tomlnext todocker-compose.yml:[server] bind_addr = "0.0.0.0:6710" deployment_key = "k_0123456789abcdef0123456789abcdef" # replace with genkey output public_host = "sync.example.com" # required, makes admin POSTs work [storage] data_dir = "/var/lib/pkv-sync" db_path = "/var/lib/pkv-sync/metadata.db"
From the project's README.