If you’re anything like me, your “second brain” lives in a folder of Markdown files managed by Obsidian. It’s fast, local-first, and endlessly extensible – until you’re on a machine that isn’t yours. A work laptop. A friend’s desktop. A Chromebook you grabbed in a pinch. Suddenly your years of linked notes are one app-install-away from being useless.
That’s the itch WebObsidian scratches.
It’s an open-source project by developer xnohat, and the pitch is refreshingly simple: point it at a folder of Markdown files and edit your notes from any browser – while staying 100% compatible with your existing Obsidian vault, .obsidian/ config and all.
What it actually is
WebObsidian is a self-hosted, single-user web app that recreates the core Obsidian experience on the server side. There’s no database, no vendor lock-in, and no syncing your notes to someone else’s cloud. One master password protects the whole thing, configuration lives in a plain data/settings.json, and the entire stack runs with a single docker compose up.
The clever part is that it’s not a clone or a reinterpretation of Obsidian – it reads and writes the same files Obsidian does. You can have the desktop app open on one machine and WebObsidian open in a browser tab on another, both pointed at the same vault, and they won’t fight each other.
The feature list reads like an Obsidian highlight reel
Scanning the README, it’s clear a lot of care went into matching the muscle memory Obsidian users already have:
- A real editor. CodeMirror 6 under the hood, with live, source, and reading views. Wikilinks, embeds, tags, callouts, task lists, KaTeX math, and Mermaid diagrams all render properly.
- A graph view. The force-directed node graph that makes Obsidian feel like a constellation of ideas, complete with fly-to-node search.
- Backlinks done right. Linked and unlinked mentions, outgoing links, tags, and an outline – all tucked into a sidebar tab strip.
- Fast search. A custom full-text and fielded search engine (they call it QMD) that supports queries like
tag:andpath:, with fuzzy and prefix matching. - Git-native sync. Pull, commit, and push your vault straight from the app, with Git LFS support for attachments and a version history you can browse and restore from.
- Public sharing. Turn any note into a clean, SEO-friendly, optionally password-protected public page.
- Community plugins. It loads a subset of actual Obsidian plugins via an API-compatibility shim – not a feature you’d expect from a side project, but there it is.
- Mobile-friendly. Drawer sidebars, edge-swipe gestures, an on-keyboard formatting toolbar – clearly built with phones and tablets in mind, not just desktop browsers.
That’s already a generous feature set for a self-hosted tool. But the part that really stands out is buried further down the README.
An API built for AI agents, not just humans
WebObsidian ships with a scoped REST API at /api/v1, designed explicitly so AI coding agents – Claude Code, Codex, Cursor, OpenCode – can read, write, and search your notes. You generate an API key with a specific scope (read, write, or search), and from there your agent can do things like:
# list notes
curl -H "X-API-Key: $KEY" "$BASE/notes?limit=10"
# create or update a note
curl -X PUT -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
-d '{"content":"# From the agent\n\nHello vault."}' \
"$BASE/notes/Agent/Generated.md"
There’s even a drop-in “agent skill” you can hand to your coding assistant that installs itself, asks for your vault URL and API key once, and then lets the agent work with your notes going forward. In a world where everyone’s racing to bolt AI onto note-taking apps, WebObsidian’s approach feels notably grounded: it’s just a well-scoped API sitting on top of files you already own.
Getting it running
True to its self-hosted philosophy, setup is about as friction-free as Docker gets:
git clone https://github.com/xnohat/webobsidian.git
cd webobsidian
cp .env.example .env
docker compose up -d --build
# open http://localhost:8787
It ships with a sample vault so the stack boots immediately, and switching to your own notes is a one-line change to VAULT_HOST_PATH in .env. Worth remembering: the default login password is 123456 – change it the moment you’re in.
For anyone with a sprawling vault, there are sensible touches too – the app auto-detects when a fresh VPS’s file-watch limits are too low and falls back to polling, and the Docker image bumps Node’s heap size for vaults with thousands of notes.
What it isn’t (yet)
The project is upfront about its current boundaries. It’s strictly single-user – there’s no real-time collaborative editing. Git sync stands in for Obsidian Sync and Publish rather than replacing them outright. And community plugin support covers only a subset of the real Obsidian API, so plugins that reach into Electron or Node internals won’t work.
None of that feels like a dealbreaker for the use case it’s solving: giving one person full, browser-based access to their own Markdown vault, from anywhere, without handing it to a third party.
Why this matters
There’s a quiet trend of people wanting to own their data again – their notes, their photos, their messages – without giving up the convenience of “just open a browser tab.” WebObsidian is a clean example of that trend applied to personal knowledge management. It’s not trying to out-feature Obsidian or replace it; it’s trying to make sure your notes are never trapped on a single device.
If you’ve ever wanted to check or edit your vault from a phone browser, a borrowed laptop, or a server you control yourself, it’s worth a look. The project is MIT-licensed, lives at github.com/xnohat/webobsidian, and – fittingly for a tool built around Markdown – is documented almost entirely in it.
