A wiki connected
to the systems it describes.
Oxynote is an open-source workspace for engineering docs.
Text, diagrams and live metrics in one editor, with a diff for every change.
docker run -d -p 8080:8080 -v oxynote_data:/oxynote/data ghcr.io/oxynote/oxynote
Where Your Systems Live
Oxynote is a workspace for the systems you run, alone or with a team. Architecture notes, API references, on-call steps and release checklists sit in one page tree, and everyone you invite can edit it at the same time.
Those pages can also query Prometheus, PostgreSQL, MySQL or MariaDB, so live metrics show up right where you write about them.
Charts That Breathe
The editor redraws the metric chart as you type a PromQL or SQL query, with thresholds and units right next to it. (Grafana macros such as $__rate_interval and $__timeFilter work here too, so a query you already trust usually moves over with a paste.)
No metric yet? Pick a pattern such as latency or error rate, and the chart draws simulated data until the real series arrives.
Variables That Follow You
Set $metric_range to the last six hours once, and each page that uses it shows the last six hours from then on. Variables like that are defined once and shared across the whole workspace, so any query on any page can read them. The values stay personal, so whatever you pick changes your queries and nobody else's.
The Whole Editor in One Menu
Type / and that is the editor: headings, lists, checklists, code, callouts, images, files, Figma embeds, Mermaid diagrams, Stripe-style API docs and live metrics. It all works out of the box, and the settings are kept to a minimum on purpose.
Markdown shortcuts like ## work too, and a few go further: %% drops in a live metric chart, and || starts a Stripe-style API doc.
Search Down to the Line
⌘K searches the whole workspace, down to a single line in a code block or a diagram's source. Results come grouped by page, and each one says what it is, such as a Bash snippet or a time series metric chart.
Typos are fine. Half a remembered word usually gets you there.
Pull Requests for Pages
Once a page is reviewable, the main branch stops taking direct edits, and changes go into a draft branch. The diff understands blocks, so a renamed API parameter and a moved chart threshold show up in red and green right where they sit.
Reviewers approve the draft without leaving the page. Merging is a separate step, so an approved draft can wait until the change it describes goes live.
Multiplayer Pages
Everyone on a page shows up as a named cursor, along with the block they're holding, and edits from several people merge as they type. Comments attach to a single word or to a whole block.
New comments and replies land in your inbox, and one click there takes you to the block they're on.
Built for People, Ready for Agents
Oxynote is designed for people first. The interface is uncluttered, so your attention stays on the system.
Agents get an interface of their own. Claude Code, Codex and many others connect over MCP and read each page as structured blocks. They change only the blocks they need and never scrape the screen.
Their edits appear live, and on a reviewable page they wait in a draft until a person approves them. Prefer to stay in the app? Rubber Duck, the built-in assistant, does the same with the model of your choice.
Simple on Purpose
Oxynote stays small by design. The things it is not are as deliberate as the things it is.
One Way to Do Each Thing
Each job has one way to get done, with defaults that already fit, so there is less to learn.
Changes Leave a Trail
Protected pages change only through approved drafts, so each change carries a diff and the name of whoever approved it.
Private by Default
Only people you invite can open your workspace, and an AI agent gets in only after you approve it.
Know When to Revisit
Point a page at the repository, container image or website it covers, and it tells its maintainers when that changes.
Built in the Open
Apache-2.0 licensed and developed in public on GitHub, so you can follow along or pitch in.
Yours to Run
One container on your own servers, so your data and your upgrade schedule stay with you.
Frequently Asked Questions
Short answers. The long ones live in the docs.
Yes, that's the goal. Metric charts are already covered: Oxynote runs your Prometheus and SQL queries, Grafana's macros included, and puts the charts inside pages you can write around, review like a pull request and search down to the line. Logs, traces and alerting are in development.
Because sooner or later the agent stops. Its context runs out, or it lacks the permission to touch what broke, and the incident lands back on a person. A lot of tooling now treats that person as an afterthought: either the agents will handle it, or developers are used to complexity anyway. Neither is true. That person does the rest alone, and the complexity of separate observability and internal docs platforms only adds to their exhaustion and mental load.
Oxynote was designed for that moment from day one. The explanation, the live metrics and the commands that fix the problem sit on one page with few settings in the way, so there is less to juggle and less to wear you down. Agents get the same context through an interface of their own, so people and agents both get more done.
Prometheus and SQL databases: PostgreSQL, MySQL and MariaDB. A Live Metrics block renders the query as a time series, a bar chart or a gauge. SQL sources need a read-only database user, so a page can never change your data.
Not yet. A cloud version is planned, and today Oxynote runs as one container on your own servers. Running from source is covered in CONTRIBUTING.md.
No. The AI assistant stays off until you set it up, and the MCP server for outside agents is optional too. The rest of Oxynote works without either.
Yes. A workspace works fine with one person, and when you do invite others, a self-hosted install has no member limit.
Apache-2.0. The source is on GitHub.
In the beginning, Oxynote was called “breathing docs”. Breathing needs oxygen, so “oxy” became the prefix and “note” followed.