Mastering Synkk. Step by step.

01 / Quickstart Guide

Synkk is a local-first, self-hostable sync server and Markdown workspace for Obsidian. Follow these steps to connect your first vault and device in under 2 minutes.

<your-vault>/.obsidian/plugins/synkk-sync/
├── manifest.json
├── main.js
└── styles.css

02 / Plugin Installation & Setup

Synkk works across macOS, Windows, Linux, iOS, and Android. Because your vault remains standard Markdown files on disk, your files are never held hostage.

Desktop Setup (macOS, Windows, Linux)

On desktop operating systems, Obsidian stores vault configurations inside the hidden .obsidian folder inside your vault root. Simply ensure community plugins are enabled in Obsidian preferences before copying the plugin files.

03 / Core Architecture & Storage Engine

Synkk is built on a local-first foundation. Your notes are stored as plain UTF-8 Markdown text files both on your local file system and on the server.

Storage Directory Layout

On the server side (Laravel 12 + SQLite WAL), files are organized by tenant, team, and vault:

storage/app/private/
└── vaults/
    └── {team_id}/
        └── {vault_slug}/
            ├── 00-Inbox/
            │   └── QuickNote.md
            ├── Projects/
            │   └── ArchitectureSpec.md
            └── .synkk/
                └── snapshots/

{
  "vault": "engineering-brain",
  "revision": 78,
  "files": {
    "Projects/Roadmap.md": {
      "hash": "f2a8c1d7e3b9a04f21e5c89731d4e28a9b6e5f1a2b3c4d5e6f7a8b9c0d1e2f3a",
      "size": 4210,
      "mtime": 1725712400
    }
  }
}

04 / Roles & Granular Path Permissions

Unlike traditional sync solutions that require all-or-nothing access to an entire vault, Synkk allows team leaders to enforce path-scoped boundary rules.

Member Roles & Capabilities

/finance/*          -> Admin Only (Hidden from general team)
/management/hr/*    -> Admin Only (Hidden)
/engineering/*      -> Editor (Team can read & edit)
/handbook/*         -> Reader (Team can read, Admins edit)

05 / Safety Shield & Data Loss Protection

Catastrophic data loss during sync usually happens when a script or device accidentally deletes hundreds of files and syncs that mass deletion across all devices.

The 10% Mass-Deletion Guard

Synkk introduces Safety Shield. If an incoming sync transaction attempts to delete more than 10% of the total notes in a vault, the server automatically halts the operation and places the transaction on hold.

06 / REST API Reference

Base API Endpoint: https://www.synkk.space/api/v1

All API requests require a valid Bearer token header: Authorization: Bearer synkk_....

curl -X GET "https://www.synkk.space/api/v1/auth/verify" \
  -H "Authorization: Bearer synkk_token123" \
  -H "Accept: application/json"

{
  "path": "Projects/Architecture.md",
  "content": "IyBBcmNoaXRlY3R1cmUgU3BlY2lmaWNhdGlvbg==",
  "hash": "f2a8c1d7e3b9a04f21e5c89731d4e28a9b6e5f1a2b3c4d5e6f7a8b9c0d1e2f3a",
  "base_version": 77
}

HTTP Status Code Reference

• 200 OK: Request succeeded cleanly.
• 401 Unauthorized: Invalid or expired device token.
• 403 Forbidden: Token lacks required path permission.
• 409 Conflict: Version collision detected (conflict copy generated).
• 410 Gone / Revoked: Device token was remotely wiped by admin.
• 422 Unprocessable Entity: SHA-256 checksum mismatch or DLP secret detected.

07 / Docker & Self-Hosting Guide

Synkk is designed for zero-fuss self-hosting on any Linux VPS, Home Lab server, or Raspberry Pi.

The production-ready docker-compose.yml includes the Nginx edge proxy, PHP 8.4-FPM runtime, PostgreSQL database, and Redis cache.

curl -fsSL https://synkk.it/install.sh | bash

Docker Compose Architecture

version: '3.8'

services:
  app:
    image: ghcr.io/tawandajosephmutsena/synkk:latest
    restart: unless-stopped
    environment:
      APP_ENV: production
      APP_KEY: base64:...
      DB_CONNECTION: pgsql
      DB_HOST: postgres
      REDIS_HOST: redis
    volumes:
      - synkk-storage:/var/www/html/storage/app/vaults
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: synkk
      POSTGRES_USER: synkk
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data

volumes:
  synkk-storage:
  pgdata:
  redisdata:

Environment Variables Checklist

08 / Ecosystem Roadmap