Obsidian Headless — Home Assistant Add-on

A Home Assistant add-on that turns your HA instance into a full Obsidian knowledge-base hub — continuous vault sync, a remote MCP server for AI assistants, and optional reMarkable tablet integration.

Obsidian is a powerful local-first note-taking app, but its sync daemon normally requires a running desktop application. If you want your vault available 24/7 — for AI tools, automations, or other services — you need something that keeps it synced without a GUI.

This add-on runs the official obsidian-headless CLI as a supervised daemon inside Home Assistant, so your vault stays in sync on your local network at all times, without a dedicated machine or cloud dependency.

It also ships two optional extras that take the vault further:

• An MCP server so AI assistants like Claude can read and search your notes from anywhere, over Tailscale, HTTPS, or a Cloudflare Tunnel.
• reMarkable Cloud sync so your handwritten tablet notes flow automatically into Obsidian — a locally-hosted, zero-cost alternative to Scrybble.

• Runs obsidian-headless as a continuously supervised s6 service
• Syncs via your existing Obsidian Sync subscription — no extra cloud services required
• Vault stored at /share/obsidian-vault, accessible to other HA add-ons
• Survives add-on restarts and updates (state persisted in /data/)
• Built-in token generator UI at http://<ha-ip>:8422/ — no CLI needed to get your auth token

• Exposes your vault over HTTP as a remote Model Context Protocol server
• AI assistants (Claude, etc.) can read, search, and write your notes
• Authentication: Bearer token and/or OAuth 2.1
• Four tunnel modes: local network, Tailscale, HTTPS reverse proxy, or Cloudflare Tunnel (via the separate cloudflared add-on) — Tailscale and Cloudflare modes require OAuth 2.1, since network-level access alone doesn't prove identity

• Syncs documents from your reMarkable tablet into Obsidian automatically
• Each document becomes a Markdown note with rich YAML front-matter (title, modified date, page count, tags) plus an embedded PDF
• Full folder hierarchy from your reMarkable is preserved in the vault
• Version-stamp caching — only re-downloads documents that have changed
• Index note (index.md) updated on every sync
• Optional OCR transcription of handwritten notebooks via a Home Assistant image-processing webhook
• Registration UI at http://<ha-ip>:8421/ — no CLI needed to pair your tablet

┌─────────────────────────────────────────────────────────┐
│                Home Assistant Add-on                    │
│                                                          │
│  ┌─────────────────┐   ┌───────────────────────────┐    │
│  │  obsidian-sync  │   │   remarkable-sync (Go)    │    │
│  │  (s6 service)   │   │   (s6 service)             │    │
│  │                 │   │  port 8421 — rM reg UI     │    │
│  │  ob sync        │   │  port 8422 — token gen     │    │
│  │  --continuous   │   │  shells out to rmapi (CLI) │    │
│  └────────┬────────┘   └──────────────┬─────────────┘    │
│           │                           ▼                  │
│           │                    ┌────────────┐            │
│           │                    │   rmapi    │──► reMarkable
│           │                    └─────┬──────┘     Cloud  │
│           ▼                          ▼                   │
│    /share/obsidian-vault  ◄── .rmdoc bundles →            │
│           │                  Markdown + PDF + OCR         │
│           ▼                                               │
│  ┌─────────────────┐                                      │
│  │ obsidian-mcp-   │                                      │
│  │ server          │  port 8420                           │
│  │ (s6 service)    │──────────────► MCP clients           │
│  └─────────────────┘   (Tailscale / HTTPS / local)        │
└─────────────────────────────────────────────────────────┘

Why Python for the MCP server? obsidian-web-mcp already implements the MCP protocol, vault search/indexing, and OAuth 2.1 — building our own from scratch (in Go or otherwise) would mean reimplementing all of that. The trade-off is a Python runtime baked into the image (see DOCS.md for how that's kept working across HA base image updates).

1. Add this repository to Home Assistant: Settings → Add-ons → Add-on Store → ⋮ → Repositories

   https://github.com/conallob/hassio-addons
   

2. Install Obsidian Headless from the store.

3. Open http://<your-ha-ip>:8422/ and sign in with your Obsidian account to generate your auth token.

4. Paste the token into obsidian_auth_token, set your vault_name, and start the add-on.

See DOCS.md for the full configuration reference.

Multi-arch images are published to the GitHub Container Registry on every push to main and on version tags.

ghcr.io/conallob/hassio-obsidian-headless:edge

Architectures: amd64, aarch64

# Build locally (aarch64 example)
podman build \
  --build-arg BUILD_FROM=ghcr.io/home-assistant/aarch64-base-debian:bookworm \
  --build-arg BUILD_ARCH=aarch64 \
  -t obsidian-headless:dev .

See CLAUDE.md for the full architecture and release workflow.

MIT — see LICENSE.