Zen笔记

Requirements

• Node.js 22+
• npm
• Go 1.22+ for the server build path
• Docker optional, for self-hosting

Install dependencies

npm ci

Self-hosting with Docker

Default Docker mounts

When you start Docker with make up, ZenNotes mounts:

• host ./vault -> container ./vault's absolute host path
• host ./data -> container /data

In practice, that means the container sees the vault at the same absolute path you chose on the host, instead of rewriting it to /workspace.

The server stores its config under /data/server.json by default.

Default Docker security behavior

The self-hosted Docker flow is now secure by default:

• the published port binds to 127.0.0.1 unless you override it
• ZenNotes generates a bootstrap auth token on first make up and stores it in ./data/auth-token
• the browser version signs in with that token once, then uses an HttpOnly session cookie
• the container runs as your local UID/GID by default, with a read-only root filesystem, no-new-privileges, and dropped Linux capabilities

Useful env vars:

• ALLOW_INSECURE_NOAUTH=1: only use this if you intentionally want to disable auth
• ZENNOTES_ALLOWED_ORIGINS: explicit browser origin allowlist
• ZENNOTES_BROWSE_ROOTS: restricts which server-side directories the picker can browse

Recommended deployment model:

• keep ZenNotes behind a reverse proxy, VPN, or private network gate
• do not expose the raw Go server directly to the public internet unless you understand the tradeoffs

Docker browse model

Important limitation:

• the Docker container can only browse folders that are mounted into it
• it cannot browse your entire host filesystem
• by default, the picker is scoped to the mounted content root unless you explicitly relax it

So if you want to browse an Obsidian vault, iCloud Drive, or another directory from the web picker, that directory needs to be mounted into the container first.

Building and packaging desktop releases

Build everything

npm run build:prod

Quick start

Relevant container env vars

The current compose/runtime flow supports:

• ZENNOTES_BIND
• ZENNOTES_CONFIG_PATH
• ZENNOTES_DEFAULT_VAULT_PATH
• ZENNOTES_BROWSE_ROOTS
• ZENNOTES_VAULT_PATH

Behavior notes:

• ZENNOTES_VAULT_PATH hard-locks the server to a specific vault path
• ZENNOTES_DEFAULT_VAULT_PATH sets the starting vault when no saved selection exists
• ZENNOTES_BROWSE_ROOTS limits what the web picker can browse
• ZENNOTES_ALLOWED_ORIGINS restricts which browser origins can connect
• ZENNOTES_ALLOW_UNSCOPED_BROWSE=1 removes browse-root enforcement
• ZENNOTES_ALLOW_INSECURE_NOAUTH=1 disables the default auth guardrail

Preview is part of the workflow

ZenNotes supports:

• edit mode
• preview mode
• split mode
• pinned reference panes
• detached note windows on desktop

MCP integration

ZenNotes ships a dedicated MCP server and desktop install flows for:

• Claude Code
• Claude Desktop
• Codex

The desktop app can:

• detect whether the ZenNotes MCP entry is installed
• install or uninstall it for each supported client
• show the exact runtime used to launch the server
• edit the server's default instructions from Settings

The MCP server exposes vault operations such as:

• reading notes
• creating notes
• moving notes
• appending to notes
• listing notes
• searching vault text
• listing files/assets
• toggling tasks

Desktop package scripts

npm run pack
npm run dist:mac
npm run dist:win
npm run dist:linux

Desktop vs web

Both runtimes share the same core app, but they do not expose identical platform features.

Desktop-only features include:

• native menus
• app updater
• floating note windows
• zen CLI install/uninstall flow
• local Raycast extension installation on macOS
• MCP install/uninstall flows for supported clients
• reveal in Finder / platform file manager
• packaging and signed releases

Web/self-hosted mode includes:

• the same shared note UI and workflows
• a Go backend for vault access and file watching
• a server-side vault picker/browser
• browser access on a LAN or home server