hassio-obsidian-headless

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.

---

Why does this exist?

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.

---

Features

Obsidian Vault Sync

• 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

MCP Server (optional)

• 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

reMarkable Cloud Sync (optional)

• 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

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                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)        │
└─────────────────────────────────────────────────────────┘

Component	Role
obsidian-headless	Official Obsidian Sync CLI
obsidian-web-mcp	Third-party Python MCP HTTP server (vault search, indexing, MCP protocol) — this add-on packages it, it is not our own implementation
remarkable-sync	Go binary — serves the pairing/registration UIs, converts synced .rmdoc bundles into Markdown notes with embedded PDFs/OCR. Delegates all reMarkable Cloud communication to rmapi rather than talking to the API directly
rmapi	Third-party reMarkable Cloud CLI (built from source) — remarkable-sync shells out to it for device registration and document sync, the same pattern used for obsidian-headless/obsidian-web-mcp

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).

---

Quick Start

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.

---

Container Image

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

Tag	When
edge	Every push to main
<sha>	Short commit SHA
0.1, 0.1.0	Version tags (v0.1.0)

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

Architectures: amd64, aarch64

---

Development

# 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.

---

License

MIT — see LICENSE.