Pkv Sync

Self-hosted, Git-native Obsidian vault sync with a built-in MCP server, search, and wiki lint.

LLM Mart 0 views 20 listing impressions

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.

CI License: AGPL-3.0-only

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 /mcp route on pkvsyncd 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

  1. Generate a deployment key:

    docker run --rm ghcr.io/cyberkurry/pkv-sync:latest genkey
    
  2. Drop config.toml next to docker-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.

Related servers

Project knowledge graph with history-checked belief staleness, changeset proposals, cost reporting

18 views

Git-native content governance for AI agents — 24 deterministic MCP tools over stdio and HTTP.

16 views

Official MCP connector for Legalize: read and search its whole open corpus, at any point in time.

14 views

AI-native, markdown-first project management. Your repo is the project manager.

6 views