Hatchdoor

Hatchdoor

Self-host your Obsidian vaults: a web UI for you, MCP for your AI agents. No Obsidian, no plugins required.

Hatchdoor reads your vault directly from disk, and any folder of Markdown notes works. No Local REST API plugin, no desktop app that has to stay running. Browse, search, and edit your notes in a fast web UI, and point a Model Context Protocol (MCP) client like Claude, Claude Code, Codex, Cursor, or Hermes at the same vault so your agent can read, search (keyword and semantic), create, edit, move, and link notes. One server manages as many vaults as you give it, every write goes through the same atomic vault operations the UI uses, with optimistic concurrency and optional automatic git commit-and-push. The web UI and your agents are two front doors to one vault.

Your Markdown files stay the source of truth. Hatchdoor builds a disposable SQLite read model for fast browsing, links, backlinks, keyword search, semantic search, graph data, and metadata. If the cache is deleted, Hatchdoor rebuilds it from the vault.

Hatchdoor was built with AI coding agents, primarily Claude Code and Codex, under close human review, with tests and a documented safety model.

▶ Try the live demo , a read-only public vault, or read the user documentation for setup and usage guides.

Contents

• What You Get
• Screenshots
• Who It Is For
• How Hatchdoor Compares
• What Is Next
• Quick Start With Docker
• Data And Safety Model
• Configuration
• MCP Agent Access
• Versioning and Git Sync
• Running Without Docker
• Troubleshooting
• Security Notes
• Development
• Project Docs
• License

What You Get

• A web UI for browsing folders and Markdown notes.
• Native multi-vault: one instance serves several vaults, each with its own source, git sync, and agent scope.
• Clean note URLs at /v/ /n/ .
• Obsidian-style wikilinks for [[Note]], [[Folder/Note]], and [[Note|Alias]], and Markdown links to .md files, both kept up to date through renames and moves. New links follow each vault's own link style.
• Saved queries: a fenced base block in Obsidian's Bases syntax draws a live table of the notes it selects, for people and agents alike.
• Markdown rendering with GitHub-flavored Markdown, math, Mermaid diagrams, frontmatter, images, attachments, and broken-link styling.
• Keyword search and semantic search.
• Recent notes, backlinks, outbound links, stats, and graph views.
• A live editor in the browser when the vault mount is writable: the note opens ready to type in, Markdown syntax shows only on the line you are on, and edits save by themselves. It works the way Obsidian's Live Preview does.
• Attachment uploads, local asset serving, and inline previews for linked PDF vault assets.
• A first-class MCP server so AI agents can read, search, create, edit, and link notes with the same safety as the UI, rename or delete a tag across a whole vault in one checked operation, and move attachments of any size through short-lived download and upload links.
• Agent reads sized for a context window: compact search hits, an outline of a long note and just the sections asked for, and an exact-string search that counts every occurrence.
• A setup checklist on a fresh install that goes from an empty instance to an agent searching your notes, with a folder picker in place of container paths.
• The manual built into the app: Help beside whatever you are doing, the same pages for agents through read_docs and search_docs, and as plain Markdown at /docs/ on every instance.
• Optional automatic git commits and pushes for Hatchdoor writes, each commit naming where its changes came from (the web UI, a named agent, or an outside edit), with sync conflicts resolved on your Git host through a recovery branch.
• PWA assets and service worker caching for common read paths.
• Distroless, rootless container image (no shell, runs as nonroot) that deploys with either Docker or Podman.

Screenshots

Knowledge graph : notes, links, and tags

Semantic + keyword search

Dark mode

Responsive & installable (PWA)

Who It Is For

Hatchdoor is useful if you have a folder of Markdown notes and want a private web interface for them.

It is beginner-friendly enough to run with Docker Compose, but it also includes advanced features for people who want agent access, git-backed vault sync, semantic search, and local development.

Hatchdoor is not a hosted sync service, not a multi-user collaboration platform, and not a replacement for Obsidian. It is a self-hosted companion for a Markdown vault you control.

How Hatchdoor Compares

The MCP-for-Obsidian field is crowded. The honest short version: if you live inside the Obsidian app and want the smallest possible bridge to it, the plugin-based tools are fine. Hatchdoor is for when you want the vault served independently of Obsidian: from a homelab box, for browsers and agents at once, across more than one vault.

Basic Memory and OpenKnowledge are good projects solving adjacent problems (agent memory, an AI-native editor). Hatchdoor overlaps them only where your notes are a vault you want served: one always-on service, for browsers and agents at once.

What Is Next

The next large feature is multi-account handling with permission scoping. Today Hatchdoor assumes a single trusted user on a private deployment, so whoever reaches the instance sees every vault it serves. The plan is to let several people and agents share one instance, each scoped to the vaults they are granted, with an admin role that manages the rest. A household or a small team could then run one Hatchdoor instead of one per person.

v2.5.0 already made vaults independent, addressable things the product manages, including vault scoping for MCP agents. What is missing is the half that was deliberately deferred: accounts, authentication, and an access boundary the server enforces rather than the UI implies. Targeted at v3.

Two other things are wanted but not slotted to a version yet:

• Agent provenance and undo. Which agent changed a note, a before/after diff beside the commit it produced, and one-click revert. Today git is the whole answer: each commit names the agent that made it, but reading a commit log is not the same as seeing what an agent did to your note.
• Vault integrity checks. A vault-scoped lint for orphaned notes, broken wikilinks, and layer markers whose declaration has vanished, so a vault an agent maintains unattended cannot quietly drift out of shape.

The product roadmap has the full set of workstreams and where each one stands.

Quick Start With Docker

Have an AI agent with a terminal, such as Claude Code or Codex? Give it this one line and it installs Hatchdoor for you, asking a few questions first:

Read https://hatchdoor.battercloud.cc/docs/deploy.md and install Hatchdoor for me.

To do it by hand, follow the steps below.

1. Requirements

You need:

• Docker and Docker Compose (Podman and podman compose also work)
• A Markdown vault folder, or an empty folder if you want to start from nothing

2. Create Your Config

Copy the example environment file:

cp .env.example .env

The defaults mount an empty vault folder beside the Compose file. To use an existing vault, uncomment its host path in .env:

HOST_VAULT_PATH=/absolute/path/to/your/markdown-vault

What these mean:

• HOST_VAULT_PATH is your Markdown vault on the host machine.
• HOST_CACHE_PATH, HOST_STATE_PATH, and HOST_MODELS_PATH are optional host-side locations for the generated cache, authoritative Vault registry, and downloaded models; Compose defaults them beside the project.

Before the first managed-Vault start, create the default authoritative state directory with access for the image's numeric nonroot user. Docker otherwise may create a missing bind source as root, leaving the registry unwritable:

mkdir -p data/state

chmod 700 data/