A local-first, AI-assisted knowledge workspace for Markdown vaults.
OpenOnyx is a professional desktop knowledge management app built around plain Markdown files, Obsidian-style workflows, graph navigation, local semantic indexing, and optional cloud collaboration. It is designed for people who want ownership of their notes while still having a modern thinking layer for search, synthesis, writing assistance, and knowledge exploration.
The app is built with Electron, React, TypeScript, CodeMirror, D3, Tailwind CSS, Transformers.js, IndexedDB, and Supabase.
OpenOnyx is for writers, researchers, engineers, students, and teams who want a serious knowledge base without surrendering their files to a proprietary silo.
| Principle | What it means |
|---|---|
| Local-first by default | Notes are normal files in normal folders. Core workflows work offline. |
| Markdown-native | Your writing stays portable, readable, and tool-friendly. |
| AI where it helps | Retrieval, suggestions, summaries, and inline writing tools are grounded in your vault. |
| Cloud when you choose | Supabase-backed sync, collaboration, and public Spaces are optional. |
| Plugin-aware | OpenOnyx targets Obsidian plugin compatibility through a tested runtime layer. |
You do not need an account, a cloud project, or an API key to write. There is no shipped phone app. Current release is v1.0.5.
A vault is any folder you choose. Your notes are the .md files in that folder. OpenOnyx reads them; it does not lock them in a database. Cache and indexes go in a .openonyx folder inside the vault — you can ignore that folder in git.
Stuck after install? Open an issue or ask in Discussions.
Pick your OS. Linux packages on this release are x86_64.
Windows
Signed by SignPath.io / SignPath Foundation.
Invoke-WebRequest -Uri https://github.com/OpenOnyx/OpenOnyx/releases/download/v1.0.5/OpenOnyx.Setup.1.0.5.exe -OutFile OpenOnyx.Setup.1.0.5.exemacOS
Apple menu → About This Mac → Chip. If it says Apple, use Apple Silicon. If it says Intel, use Intel.
- Apple Silicon — OpenOnyx-1.0.5-arm64.dmg
- Intel — OpenOnyx-1.0.5.dmg
Open the .dmg, drag OpenOnyx into Applications, then launch it from there.
# Apple Silicon
curl -LO https://github.com/OpenOnyx/OpenOnyx/releases/download/v1.0.5/OpenOnyx-1.0.5-arm64.dmg
# Intel
curl -LO https://github.com/OpenOnyx/OpenOnyx/releases/download/v1.0.5/OpenOnyx-1.0.5.dmgIf Gatekeeper blocks the app: right-click → Open, or xattr -cr /Applications/OpenOnyx.app.
Linux
- AppImage
- Debian / Ubuntu — openonyx_1.0.5_amd64.deb
- Arch — openonyx-1.0.5-1-x86_64.pkg.tar.zst
There is no official .rpm.
# AppImage
curl -LO https://github.com/OpenOnyx/OpenOnyx/releases/download/v1.0.5/OpenOnyx-1.0.5.AppImage
chmod +x OpenOnyx-1.0.5.AppImage
./OpenOnyx-1.0.5.AppImage
# Debian / Ubuntu
curl -LO https://github.com/OpenOnyx/OpenOnyx/releases/download/v1.0.5/openonyx_1.0.5_amd64.deb
sudo dpkg -i openonyx_1.0.5_amd64.deb
# Arch
curl -LO https://github.com/OpenOnyx/OpenOnyx/releases/download/v1.0.5/openonyx-1.0.5-1-x86_64.pkg.tar.zst
sudo pacman -U openonyx-1.0.5-1-x86_64.pkg.tar.zstmacOS and Linux — one command (detects the OS and installs the matching package):
curl -fsSL https://raw.githubusercontent.com/OpenOnyx/OpenOnyx/main/scripts/install.sh | bashThe welcome screen can create a new folder or open an existing one. That folder is the vault.
- New to this: create an empty folder. You will add notes inside the app.
- Coming from Obsidian: open the folder you already use. Notes,
[[wiki links]], tags, and.canvasfiles stay on disk. You can keep using Obsidian on the same folder. - Switch later with File → Open Vault.
Ctrl/Cmd+Ois the note switcher, not “open another vault.”
No account. Writing works offline.
Ctrl/Cmd+N— new note. Type.Ctrl/Cmd+Ssaves the.mdfile in the vault.- Link notes with
[[other-note]]. Ctrl/Cmd+Ojumps to a note by name.Ctrl/Cmd+Shift+Fsearches file contents.Ctrl/Cmd+Pis the command palette.Ctrl/Cmd+Gopens the graph (your wiki links as a map).- Open Spaces, create a local Space, and ask a question over the folder. The first time may download the on-device embedding model; after that, retrieval stays local. Answers that call a remote model need an OpenAI or OpenRouter key in Settings. Local embeddings do not.
| Keys | What it does |
|---|---|
Ctrl/Cmd+N |
New note |
Ctrl/Cmd+S |
Save |
Ctrl/Cmd+O |
Jump to a note |
Ctrl/Cmd+Shift+F |
Search the vault |
Ctrl/Cmd+P |
Command palette |
Ctrl/Cmd+G |
Graph |
| You want | What you set up |
|---|---|
| Write, search, graph | Nothing |
| Local Spaces (index the folder, retrieve with citations) | Nothing. Model caches on first use. |
| Inline rewrite / Spaces answers from a remote model | Your OpenAI or OpenRouter key in Settings |
| Sync Spaces across machines | Your own Supabase project (see To start developing) |
| Live multiplayer editing | Sign in, create or link a private cloud space, and invite collaborators |
Community plugins go through an Obsidian-compatible runtime. Compatibility is tested; it is not a promise that every plugin is perfect.
You need Node.js 22 or newer and npm 9+. You do not need this if you only want to use the desktop app above.
git clone https://github.com/OpenOnyx/OpenOnyx.git
cd OpenOnyx
npm install
npm run devThat builds the Electron main process, starts Vite at http://localhost:5173, and launches the desktop app.
If Electron’s postinstall download was skipped:
npm config set ignore-scripts false
npm rebuild electron
npm run dev| Command | Purpose |
|---|---|
npm run dev |
Desktop app + Vite |
npm run lint |
Typecheck (tsc --noEmit) |
npm run test |
Unit tests |
npm run test:plugin-runtime |
Plugin API runtime tests |
npm run test:all-checks |
Full contributor gate |
npm run package |
Local installers in release/ |
Platform packages: npm run package:mac, package:win, package:linux. Tagged GitHub releases are built by .github/workflows/release.yml. Distro templates are in packaging/.
Optional Spaces sync uses .env.example → .env.local (VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY) and supabase/schema.sql. Local vaults, search, graph, and local Spaces need no environment variables.
The website is a separate Vite app:
cd website
npm install
npm run devThe product site and user guide live in website/. Run it locally with the commands above. openonyx.dev is a placeholder — do not treat that URL as live docs until it is.
Contributor technical notes: docs/ (Spaces internals, plugin API matrix).
We love our contributors. If you want to help, start with CONTRIBUTING.md. Fork, branch from main, keep the change small, run npm run lint and the tests that match what you touched, then open a pull request against OpenOnyx/OpenOnyx.
This community has a Code of Conduct. Please follow it.
Good first issues are labeled good first issue.
What is shipped, what is next, and what is later: docs/roadmap.md. The living backlog is GitHub Issues.
- GitHub Issues — bugs and features
- GitHub Discussions — questions
- openonyx@gmail.com — project contact
- Security reports: SECURITY.md (not the public tracker)
