Oxynote

Your system, with subtitles.

A self-hosted workspace that puts live metric charts inside the pages that
explain them. The charts run your Prometheus and SQL queries, and a change
to a page goes through a draft, a diff and an approval, like a pull
request. From the authors of
ttlcache.

Why Oxynote Exists

Keeping a service running takes several tools. You read about it in a wiki
such as Notion and watch its metric charts in Grafana or Datadog, while the
commands that fix it sit in a terminal history or a chat thread. When
something breaks, you connect all of that by hand, across tools with
separate logins and separate histories.

Oxynote is a new kind of tool because it puts the explanation and the live
metric charts on one page. Each chart runs its own Prometheus or SQL query,
and one draft carries a change to the chart and its text through the same
review.

The goal is to watch and run the service from that same page. Its uptime
monitor, its logs, a view into its database and its admin actions would sit
next to the explanation, and changes to them would go through the same
review. All of them are in development.

The long version is a bit of a rant, but it explains the personal why

For a long time, the most reliable documentation at my company was the
Slack chat I had with myself. How it got that way starts with
metric charts. We had a lot of them: Grafana, Sentry, for some reason a bit
of Datadog, and a few custom self-hosted HTML pages with charts on them.
On top of that, I was encouraged to run my own health checks for the
deployments I owned (why that could not live in Grafana or anything like
it, nobody could tell me). Those deployments were services pulling
financial market data over websockets. Under heavy volume they leaked
memory and got OOM killed. There was a bug in there somewhere that we
were chasing and could not find for a while, and in the meantime every
kill meant missed events, and missed events meant running backfill
scripts by hand. None of those charts showed any of that. So: cron, curl
against each service's status endpoint, and the result posted to me
privately on Slack. Not convenient at all.

Then there was everything else. Internal wikis still describing
deployment procedures for trial products that had ended. Secret vaults.
Server management commands and curl requests. None of it lived in one
place, and access was its own problem: each of these had a different
owner who could grant it, so a lot of my time went into finding out who
that was and then finding them. Since we talked on Slack, that is where
I asked for all of it, and that is where people answered, sometimes with
plain credentials (the horror). To not lose any of it, I forwarded those
messages to the chat with myself, which is how that chat became my
source of truth for a long time: links to the specific Grafana
dashboards that mattered out of the many we had, example curl requests
against other teams' services so I could match their responses when
integrating (neither the requests nor the responses were documented
anywhere), and server IPs with notes on what was deployed where.

Naturally, I did try to fix it. I wrote Notion docs and linked the
Grafana charts from them, and for a while that was fine. Then they
drifted apart. One doc explained the labels on our ingestion-rate chart,
market, region and so on, but new labels kept being added, nobody
documented them, half were not even used in the chart, and each one cost
Prometheus another time series. Keeping a doc and a chart in sync meant
links on both sides, in Notion and in Grafana, which was more work than
I wanted, plus switching browser tabs just to check that the explanation
and the chart still meant the same thing. And that was only
observability. Beyond it, admin actions were specific curl requests, and
feature flags lived in a service disconnected from everything else. All
of it deserved a proper review flow, like on GitHub, with diffs that work
for text, metric charts and other visual structures. Instead it had
none.

David (@davseby), who started Oxynote with me
(@swithek), was the one who had to work
through a system and its documents the first time he was on call, at a
different company. He had years of Grafana and internal docs behind him and
expected it to be routine. What he got was Datadog, which he had never used,
and a wildly different Notion structure. Then, on that first shift, the
services that enrich image metadata failed. Search over user uploads turned
inaccurate, and from there it cascaded through the product. Monitors fired,
but none of them linked anywhere or said which service had started failing,
which made for a nerve-racking night of tying things together by hand. The
metric showing one service overloaded and unresponsive existed the whole
time. Datadog's UI is convoluted, though, and nothing explained what any
chart tracked, so David never found it. An AI agent connected to Datadog's
MCP server did.

What both of us wanted was the metric chart, the explanation, the command
and the flag on one page, edited together, reviewed like a pull request,
and readable by a tired person at night or by an agent. Each tool we had
was great at one of those things and paid little attention to the others.
So Oxynote starts with the pieces we needed most: pages people edit
together, live metric charts, reviews and Stripe-style API docs. Uptime
monitors, AI evals, a database viewer and admin actions are in
development.

Quick Start

Oxynote is one container. Start it with Docker:sh docker run -d -p 8080:8080 \ -v oxynote_data:/oxynote/data \ ghcr.io/oxynote/oxynote

Open http://localhost:8080 and sign in as admin@example.com with the
password oxynote-admin-1234. The login page shows both until you change
the password, so change it in the settings before anyone else can reach the
instance.

docker/prod/README.md covers the configuration,
from a real domain to an external PostgreSQL. To run from source, see
CONTRIBUTING.md.

Features

Oxynote keeps the pages about your systems, such as architecture notes, API
references, on-call steps and release checklists, in one page tree. Those
pages can query Prometheus, PostgreSQL, MySQL or MariaDB, so the live
metrics sit right where you write about them.

Live Metric Charts

A Live Metrics block draws a time series, a bar chart or a gauge from one
or more PromQL or SQL queries, and the editor redraws it as you type.
Thresholds and units sit next to the query. Grafana macros such as
$__rate_interval and $__timeFilter work too, so a query you already
use in Grafana 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. SQL sources need a
read-only database user, so a page can never change your data.

Variables

Variables are defined once for the whole workspace, and any query on any
page can read them. $metric_range comes built in: set it to the last six
hours, and each chart that uses it shows the last six hours from then on.
The values you pick apply only to you, so they change your charts and
nobody else's.

Blocks

Type / for the block menu: headings, lists, checklists, code, callouts,
images, files, Figma embeds, Mermaid diagrams, Stripe-style API docs and
live metrics. Markdown shortcuts such as ## work as you type. Two go
further: %% adds a live metric chart, and · starts an API doc with the
fields on one side and an example request on the other.

Search

⌘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
matched, such as a Bash snippet or a time series chart. Typos are fine too.

Reviews

Make a page reviewable, and its main branch stops taking direct edits.
Changes go into a draft branch instead. The diff works on 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 on the page itself. Merging is a separate step,
so an approved draft can wait until the change it describes goes live.

Collaboration

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 a whole block. New comments and replies land in your
inbox, and one click there opens the block they're on.

Agents and MCP

Oxynote is designed for people first, and agents get an interface of their
own. Claude Code, Codex and many other MCP clients connect once you approve
them. They read each page as structured blocks and change only the blocks
they need. Their edits appear live, and on a reviewable page they wait in a
draft until a person approves them.

Rubber Duck, the built-in assistant, does the same inside the app. It runs
on a model from Anthropic, OpenAI, Google or OpenRouter, or a local one
through Ollama. Both stay optional: the assistant is off until you set it
up, as docs/ai.md describes, and the rest of Oxynote works
without either.

Simple on Purpose

Oxynote has few settings, on purpose. Each job has one way to get done,
with defaults that already fit, so there is less to learn. The rest of the
design follows from a few fixed choices:

• Protected pages change only through approved drafts, so each change
  carries a diff and the name of whoever approved it.
• Only people you invite can open your workspace, and an AI agent gets in
  only after you approve it.
• A page can depend on things outside Oxynote, such as a config file in
  your repository, the container image you deploy or a vendor's API docs.
  An optional freshness hook watches each one, and when it changes, the
  page's maintainers get a reminder to update the parts that rely on it.
• The code is Apache-2.0 licensed and developed in public.
• Oxynote runs as one container on your own servers, so your data and your
  upgrade schedule stay with you.

In Development

The goal is one place to explain, watch and run your systems. Uptime
monitors, AI evals, a database viewer and admin actions are in development,
along with logs, traces and alerting.

FAQ

Can it replace Grafana or Datadog? That is the goal. Metric charts are
covered today: Oxynote runs your Prometheus and SQL queries, Grafana's
macros included, inside pages you can write around and review like a pull
request. Logs, traces and alerting are in development.

Is there a cloud version? Not yet. A cloud version is planned, and
today Oxynote runs as one container on your own servers.

Do I need AI to use it? No. The assistant stays off until you set it
up, and the MCP server is optional too.

Is it worth using by myself? Yes. A workspace works fine with one
person, and when you do invite others, a self-hosted install has no member
limit.

Why the name? In the beginning, Oxynote was called "breathing docs".
Breathing needs oxygen, so "oxy" became the prefix and "note" followed.

Community

Ask questions on Discord, where the people
building Oxynote answer them. For a bug or an idea,
open an issue. To report a
vulnerability, follow SECURITY.md.