v2.5.0

Hatchdoor v2.5.0

Important

Container deployments must add a new bind mount before upgrading. Vault identities now live in a registry that must persist across restarts; without the mount below, the automatic first-start migration is silently lost on every restart. A single-Vault install is imported into that registry automatically; nothing on disk moves and no note is touched. If a token uploads attachments over HTTP using the MCP bearer token, that stops working unless MCP write mode is enabled. See "Required upgrade actions" below.

Hi everyone, super excited to share with you this latest release of Hatchdoor as we are welcoming a software engineer as a new co-developer of the app @alemhnan!

It is a major release (more than doubled the number of lines of code in the app) and took us way longer than expected, but it is finally here and we're sure you're gonna love it! It brings tons of things but most notably the possibility to handle multiple vaults in one instance. All of them can be handled via git, cloned directly from within the app. You can also handle settings directly in the webUI (quite a big UI/UX refactor) while still accessing all of them via MCP.

You also now have access to an online documentation for setting up Hatchdoor https://docs-hatchdoor.battercloud.cc/

Now, all this awesomeness comes at a cost... A full reindex and breaking changes, only for the greater good of course.

New Features

• Multiple Vaults. Hatchdoor can now hold more than one Vault. Add, pause, and disconnect them from Settings, then browse them together or switch to just one, useful once your notes span more than a single folder. A single-Vault install is unaffected until a second Vault is added.
• Git-backed Vaults. A Vault can now be backed by a Git repository instead of only a local folder. Connect a repo already in use, have Hatchdoor clone one for you, or keep local version history in a folder it manages, with a sync console that reports exactly what happened on each sync.
• Changes panel. A new panel lists notes that changed on disk since you last looked, so you can see what shifted without hunting through folders.

Breaking Changes

1. Add the /data/state bind mount

Vault identities and source definitions (vaults.json) are now authoritative instance state, not a rebuildable cache. Add this to .env:

HOST_STATE_PATH=./data/state

And this mount to docker-compose.yml:

${HOST_STATE_PATH:-./data/state}:/data/state

The rootless image writes the registry as numeric user/group 65532:65532. Create the directory and set ownership before starting Docker so it is not auto-created as root-owned:

mkdir -p data/state
chmod 700 data/state
sudo chown 65532:65532 data/state

For rootless Podman, use podman unshare chown 65532:65532 data/state instead.

Use the checked-in docker-compose.yml as the canonical example. Without this mount, the registry created by the automatic Vault import below is lost on every container restart or upgrade.

2. Automatic Vault import

On first v2.5.0 start, an existing single-Vault deployment is imported into a Vault registry stored alongside the cache (/data/state/vaults.json). Per-vault environment variables (HATCHDOOR_EXCLUDE, the HATCHDOOR_GIT_* family) are read once and stored as that Vault's own settings; Hatchdoor then serves a restricted recovery screen until those now-obsolete .env lines are removed and the container restarted.

Follow the legacy single-Vault upgrade guide before upgrading: back up the Vault, its .git directory if present, and /data/state, and make sure the state directory has the right ownership for the rootless container.

Action: leave the variables in place for the first upgraded start, then remove the variables Hatchdoor names and start it again. Manage them in Settings per Vault from then on.

3. Review the MCP attachment-upload change

A read-only MCP token can no longer upload attachments over HTTP. The multipart POST /api/attachment endpoint now accepts an MCP bearer token only while MCP and MCP write mode are both enabled.

Action: if an agent uploads attachments over HTTP using the MCP bearer token, either enable MCP write mode or switch that workflow to the web bearer token. Call get_attachment_import_config to see the upload methods and limits available to a session.

Improvements

• Faster first look at a Vault. Browsing no longer waits for search indexing to finish: a Vault's structure appears as soon as it's read, so notes are open-able while the search index builds in the background.
• Smarter attachment links. A bare ![[Some document.pdf]]-style embed now finds the right file anywhere in the Vault, not just next to the note that references it, so vaults that keep attachments in one shared folder stop showing broken images and PDFs.
• Clearer navigation. The sidebar now shows what you're browsing at a glance, the note-creation dialog is easier to use, and a "New note" button is always reachable at the bottom of the sidebar.
• Vault-aware search. Search results can be filtered to a specific Vault, and search now says plainly when a Vault couldn't be searched instead of quietly returning fewer results. Vault-scoped MCP tools let agents target one Vault or all of them the same way.

Bug Fixes

• Fixed an issue where opening a note could highlight it in multiple sidebar lists at once.
• Fixed the explorer continuing to show notes and whole Vaults after they'd been removed.
• Fixed one unreadable file being able to stop indexing for an entire Vault.
• Fixed a public demo deployment revealing local file paths and disabled/hidden content it shouldn't have shown.

See CHANGELOG.md for the complete list of changes.