WikiOS turns an Obsidian vault into a local web app. It lets you browse notes through a homepage, search, article pages, a graph view, and stats.

Built by Ansub, co-founder of Supafast - we build websites for B2B SaaS & AI companies.

• Connects to an Obsidian-compatible markdown folder
• Builds a local searchable index
• Gives you a clean web interface for exploring your notes
• Watches the vault for changes and updates the index automatically

Clone and launch:

git clone https://github.com/Ansub/wiki-os.git wiki-os && cd wiki-os && npm run first-run

WikiOS will open in your browser and guide you through choosing a vault. You can also use the bundled demo vault on first run.

WikiOS setup and maintenance commands now run through Node-based helpers, so the same commands work on Windows, macOS, and Linux.

Run the bundled demo vault in Docker:

docker compose up --build

The container uses the sample vault from sample-vault/ by default. To point it at your own vault, change the /vault volume mount and the WIKI_ROOT environment variable in docker-compose.yml.

For a direct build and run:

docker build -t wiki-os .
docker run --rm -p 5211:5211 -e WIKI_ROOT=/vault -v /path/to/your/vault:/vault:ro -v wiki-os-data:/data wiki-os

• Homepage with featured notes, recent notes, and people highlights
• Fast local search
• Clean article pages
• Graph view
• Stats view
• Manual reindex support
• Automatic file watching
• Local-first setup with no cloud requirement

For normal users, use:

npm start

For contributors working on WikiOS itself, use:

npm run dev

dev runs a split frontend/backend setup for faster iteration.

• src/client/ contains the React app, routes, and UI components
• src/server/ contains the Fastify server, setup flow, runtime config, and platform helpers
• src/lib/ contains the wiki core
• sample-vault/ contains the bundled demo content
• scripts/ contains launch, deploy, and smoke-test helpers

• npm run first-run installs dependencies and starts the guided first-run flow
• npm start starts the app in user mode
• npm run dev starts the contributor split client/server setup
• npm run build builds the client and server
• npm run serve runs the already-built server
• npm run deploy runs the deployment helper
• npm run smoke-test runs the smoke test helper
• docker compose up --build runs the app in Docker with the bundled demo vault

• WIKI_ROOT bootstraps the app with a vault path
• WIKIOS_FORCE_WIKI_ROOT forces a temporary per-process vault override
• PORT sets the server port
• WIKIOS_INDEX_DB overrides the SQLite index path
• WIKIOS_ADMIN_TOKEN protects the manual reindex endpoint
• WIKIOS_DISABLE_WATCH=1 disables filesystem watching

By default, WikiOS saves the selected vault in ~/.wiki-os/config.json and stores hashed SQLite indexes under ~/.wiki-os/indexes/.

WikiOS treats People as an explicit, user-controlled concept first. By default it recognizes people from:

• frontmatter keys like person, people, type, kind, and entity
• tags like person, people, biography, and biographies
• folders like people/, person/, biographies/, and biography/

You can customize this in wiki-os.config.ts with people.mode:

• explicit is the safest default
• hybrid allows broader inference after explicit metadata
• off hides People entirely

Local person overrides are saved in ~/.wiki-os/config.json and do not rewrite your notes.

MIT