obaass — obsidian as-a safe-ish service
Run Obsidian headlessly on a server. One docker compose up gives you three compounding capabilities:
- Multi-Device Sync — Obsidian Sync keeps the server copy current with all your devices
- Encrypted Backup — Every change gets a git commit with an AI-generated message + encrypted offsite backup
- AI Agent Access — Claude (or any MCP client) can read and write your vault
Why
Obsidian is a desktop app. No server mode. No native API. Sync is built into the desktop client. Every feature assumes a human sitting at a screen.
Obsidian v1.8+ shipped a native CLI that talks to the running app via IPC. That was the inflection point — suddenly you could control Obsidian programmatically without a GUI, a REST API plugin, or a VNC desktop environment. obaass exists because of that release.
obaass runs the desktop app headlessly on a server. That single decision unlocks capabilities Obsidian was never designed to support — and they compound:
- Phone edit via Sync -> Server receives it -> Backup captures it -> AI can read it via MCP
- AI writes a note via MCP -> Sync propagates to all devices -> Backup captures the change
- Backup restores a file -> Sync propagates the restore -> AI and all devices see it
Your vault becomes a living, distributed knowledge base accessible from any device, any AI agent, and recoverable from any point in time.
How It Works
Mermaid source
graph TB
subgraph clients["Clients"]
direction LR
phone["Phone / iPad / Mac"]
desktop["Desktop Obsidian<br/>w/ obsidi-claude"]
claude_ai["Claude.ai"]
end
sync_cloud["Obsidian Sync Cloud"]
subgraph auth["Auth and Ingress - optional, recommended"]
direction LR
ts["Tailscale Gateway"]
proxy["Traefik + Authelia"]
agw["Agentgateway"]
ts --> proxy --> agw
end
subgraph server["the safe-ish stack"]
subgraph headless["obsidi-headless"]
obs_app["Obsidian App<br/>w/ Native Sync"]
obs_mcp["obsidi-mcp plugin"]
end
backup["obsidi-backup"]
vault["Vault"]
end
offsite["Offsite Storage"]
phone ---|sync| sync_cloud
desktop ---|sync| sync_cloud
sync_cloud ---|sync| obs_app
claude_ai -- MCP --> ts
desktop -. MCP .-> proxy
agw -- MCP --> obs_mcp
obs_app --> vault
vault --> backup
backup -- encrypted --> offsite
obsidi-headless
The obsidi-headless image runs the Obsidian desktop app with a virtual framebuffer (Xvfb) instead of a real display. Electron needs a display server — Xvfb satisfies that requirement with zero overhead. No VNC, no desktop environment, no window manager.
Obsidian Sync runs inside the app, keeping the server-side vault in sync with all your devices. The native CLI (Obsidian 1.12+) provides programmatic access.
obsidi-backup
The obsidi-backup sidecar watches the vault directory for filesystem changes using inotify. After a configurable debounce period (default: 5 minutes), it:
- Commits changes to git with an AI-generated message describing what changed (or falls back to a timestamp)
- Encrypts and deduplicates to offsite storage via restic
- Prunes old snapshots per retention policy (7 daily, 4 weekly, 12 monthly)
- Notifies via Discord, Slack, or generic webhook
obsidi-mcp
An Obsidian community plugin that runs inside the headless container, exposing vault operations as MCP tools. AI agents (Claude.ai, obsidi-claude, or any MCP client) connect through your auth/ingress layer to read and write notes, search, manage tags, and more. See docs/mcp-integration.md for the full setup guide.
obsidi-claude
A chatbot-style UI plugin for the desktop Obsidian app. It connects to the server's obsidi-mcp over the network — so you can chat with your vault from your laptop while the server handles the heavy lifting, backup, and sync.
Components
