mdnest Documentation
Privately-hosted markdown notes — for one person or a small team.
Deploy on a spare machine, a home server, a cloud VM, or behind a corporate VPN. Run it as a personal knowledge base or as a small company's shared knowledge base where everyone signs in with their corporate SSO and access is scoped per namespace. Notes are plain .md files on disk; the engine adds editing, search, comments, AI integration, and team-level access control on top.
What it does
- Solo or team — same engine. Single-user mode (no database) for a private knowledge base, or multi-user mode with a three-tier role hierarchy and per-namespace access grants.
- Corporate SSO with one setting. Point mdnest at your OIDC provider — Google Workspace, Okta, Microsoft Entra, Keycloak, Auth0 — and users sign in with their existing corporate accounts. The IdP handles MFA. See SSO setup.
- Namespace-scoped admins. One or two SuperAdmins overall, plus per-team Admins who manage just their own namespace — invite users, manage grants, trigger git-sync — without seeing other teams' data.
- Live collaboration. See who's editing, where their cursor is, and what they're typing. Inline comments with threaded replies anchored to invisible UUIDs that survive moves and renames.
- Live rich editor. Obsidian-style editing where markdown renders inline as you type. Click-to-edit tables and Mermaid diagram labels.
- Plain files, zero lock-in.
.mdfiles in directories on disk.cat,grep,git, VS Code — every tool you already use just works. - AI-native. Built-in MCP server lets Claude, Cursor, and other AI agents read, write, search, and organize your notes.
- REST API + multi-server CLI.
mdnest read @work/eng/spec.mdfrom any terminal. API tokens scoped to the creator's current access — revoke a grant, the token loses that namespace immediately. - Private by default. Binds to localhost. Add Tailscale for solo remote access, or a TLS reverse proxy (Caddy / nginx / Cloudflare Tunnel) for a team install.
- Git backup on your terms. Optional sidecar auto-commits and pushes to a private repo on a schedule you control.
Getting started
Follow the Quick Start to install and run mdnest in under 3 minutes, or the Setup Guide for the full configuration reference.
Learn more
- Quick Start — get running in 3 minutes
- Setup & Configuration — every config option, env var, mount layout
- User Guide — editor, comments, live collab, roles, admin panel
- Security — threat model, identity, authorization, role hierarchy
- API Reference — REST endpoints with curl examples
- Architecture — backend, frontend, database, identity providers
- CLI —
mdnestcommand-line tool for terminal access (multi-server) - SSO Setup — corporate OIDC (Google / Okta / Entra / Keycloak / Auth0)
- Firebase Setup — Firebase Auth peer mode
- Changelog — what's new