Who Oxynote is for#
Platform teams documenting the services they operate
Platform or infrastructure teams that own a fleet of services need runbooks, deployment notes, and health dashboards in one place. Oxynote lets them embed the Prometheus metrics for a service on the same page as the runbook describing what to do when those metrics cross a threshold. Changes to the runbook go through the same review flow as changes to the chart configuration.
Skip if:
If your team does not run Prometheus or a SQL-queryable metrics store, Oxynote's core differentiation over a plain wiki is not available. A standard Notion or Confluence workspace is simpler for pure text documentation without live data.
Backend engineers writing internal API documentation
Backend engineers who want Stripe-style split docs for internal services can use Oxynote's Split Documentation block to show request parameters and a live latency chart side by side. The result updates in real time as the service runs, so the documentation reflects actual behavior rather than a manually maintained description.
Skip if:
If your internal APIs are already documented with a dedicated generator like Swagger UI or Redoc, adding Oxynote as a second documentation system adds coordination overhead. Oxynote fits best when the team wants API docs and operational context together.
Engineering teams building AI agent workflows
MCP-compatible agents such as Claude Code or Codex can connect to Oxynote over OAuth and query both the wiki pages and the metric data directly. Teams building incident-response agents or automated operations workflows can point those agents at an Oxynote workspace for a single interface over both the wiki content and live metric data.
Skip if:
If your agents do not support MCP or you are not building any agentic workflows yet, this integration provides no immediate value. Evaluate Oxynote on its wiki and metrics features alone.
The problem it solves#
Monitoring and documentation live in separate tools, and they drift apart. In most engineering teams, Grafana holds the dashboards, Notion or Confluence holds the runbooks, and neither is aware of the other. When a chart changes, the explanation does not update. When a threshold moves, the reason does not move with it. During an incident, the engineer on call must switch between tabs to connect a spike to its meaning.
The same problem runs through internal API documentation. Service endpoints change, request and response fields get added or removed, but the documentation lives somewhere else and catches up only when someone has time to update it. Runbooks describing admin commands and server procedures accumulate in wikis nobody trusts because nobody can tell whether the doc reflects what is deployed now or what was deployed a year ago.
How it solves it#
Inline Prometheus and SQL metric charts
A Live Metrics block runs a Prometheus query, a PostgreSQL query, a MySQL query, or a MariaDB query and renders the result as a time series, bar chart, or gauge directly inside the page. Multiple blocks side by side form a metric grid, which works like a Grafana dashboard embedded inside a document, with the explanation, thresholds, and runbook instructions surrounding the charts.
Draft, diff, and approval review flow
Any page can be set to require a review before changes land. Every edit opens a draft branch; the diff view shows renamed endpoints, reworded sentences, and changed chart queries together in one red-and-green view. Reviewers approve, the draft merges to main, and main can be protected to prevent direct edits. The flow treats documentation changes the same way pull requests treat code changes.
Real-time collaborative editing
Multiple people can edit the same page at the same time. You see who is on the page, which block they are holding, and where they are typing, with no overwrite conflicts. Comments attach to a specific word, to a line inside a Mermaid diagram's source, or to a whole chart, and they carry replies and can be resolved when the change lands. Every mention and reply arrives in an inbox.
Freshness hooks for tracked dependencies
A block or a whole page can track an external dependency, such as a GitHub file, a container image, a web URL, or a date. When that dependency changes, the assigned maintainers get a reminder. Doc rot changes from a passive problem into an active signal. When you deploy a new image version, the pages that reference it notify the people responsible for keeping them current.
Built-in AI assistant with MCP access
Rubber Duck, the built-in assistant, reads and edits pages and runs the same Prometheus and SQL queries the metric blocks run. You choose the model: Anthropic, OpenAI, Google, OpenRouter, or a local model through Ollama. MCP-compatible clients such as Claude Code and Codex connect to Oxynote over OAuth and can read pages, edit them, and run metric queries, the same capabilities available to Rubber Duck.
Split API documentation blocks
A Split Documentation block puts request parameters or response fields on the left and the live endpoint, example curl commands, and a latency chart on the right, similar to how Stripe presents its API documentation. Internal service documentation built this way shows the schema and the live behavior on one page without a separate documentation generator or spec-to-HTML pipeline.
Strengths and trade-offs#
Strengths
- Docs and charts change together, reviewed togetherBecause metrics and documentation live in the same page, a draft branch carries both through one diff and one approval. Grafana and Notion as separate tools each keep their own history, so there is no way to review a chart change and its documentation update as one commit. Oxynote's review flow treats the metric query and the prose around it as one atomic change.
- Apache 2.0 license, no per-seat feesApache 2.0 allows running Oxynote on commercial infrastructure, modifying the source, and redistributing it without licensing fees. There are no per-seat or per-editor charges for the self-hosted version. Notion and Confluence both charge per seat for team access; a growing engineering team on Oxynote pays once for the server.
- Single Docker container, no external database requiredThe quick-start is one docker run command with a data volume mount. Oxynote stores its own data without requiring a separately provisioned database. For teams that want a self-hosted wiki without a Postgres or MySQL prerequisite, setup reduces to the time it takes to pull the image and start the container.
- AI agent access over MCPMCP-compatible clients such as Claude Code and Codex connect to Oxynote over OAuth and can read pages, edit them, and run metric queries. An agent responding to an alert can read the relevant runbook and query the Prometheus data for that service without switching tools, since both the documentation and the metric queries live in the same workspace.
Trade-offs
- -No hosted service availableOxynote is self-hosted only. There is no managed cloud option, so every team that wants to use it needs to run and maintain the container themselves. This rules out teams without infrastructure to host another service or those that require a vendor-managed SaaS option.
- -Logs and alerting not yet supportedThe live metrics layer currently covers Prometheus and SQL. Log ingestion and alert management are not yet implemented, as the project FAQ states directly. Teams that need a unified view of metrics, logs, and alerts in the same wiki page will need to use Grafana or another tool alongside Oxynote for those parts.
- -Early-stage project with limited production track recordOxynote was created in August 2026 and had 214 stars and 65 open issues at the time of writing. Teams with low tolerance for bugs or breaking changes should evaluate carefully, follow releases closely, and maintain their own backups of the data volume.
Oxynote vs alternatives#
Oxynote vs Notion
Oxynote and Notion overlap on structured docs, real-time editing, and a block-based page editor. The key difference is that Notion is a general-purpose workspace with no native metric charts, while Oxynote embeds live Prometheus and SQL data directly into pages.
| Feature | Oxynote | Notion |
|---|---|---|
| License | Apache 2.0 | Proprietary |
| Self-hosting | Yes (Docker) | No |
| Live metric charts | Prometheus, SQL | No |
| Draft/diff review flow | Yes | No |
| MCP agent access | Yes (OAuth) | No |
| Pricing | Free self-hosted | Per-seat subscription |
Oxynote is the better choice for engineering teams that need runbooks, API docs, and system metrics in one place with a review flow that treats chart and prose changes together. Notion's embedded Grafana panels require users to be signed into Grafana to render and do not travel through Notion's version history as a unified change. For general knowledge management, marketing wikis, or company handbooks that do not touch operational metrics, Notion is more mature, has a wider range of integrations, and offers a hosted service with no infrastructure requirements.
Oxynote vs Confluence
Confluence is Atlassian's wiki, widely used in engineering organizations alongside Jira. Like Notion, it has no native metric chart capability; Grafana or Datadog data reaches it only through embeds or third-party plugins, each with its own authentication and rendering constraints.
| Feature | Oxynote | Confluence |
|---|---|---|
| License | Apache 2.0 | Proprietary |
| Self-hosting | Yes (Docker) | Cloud or Data Center (paid) |
| Live metric charts | Prometheus, SQL | No native; third-party plugins |
| Draft/diff review | Yes, built-in | Page versioning only |
| Per-seat pricing | None (self-hosted) | Per-user licensing |
| MCP agent access | Yes (OAuth) | No |
Oxynote is the better choice for teams that want a self-hosted wiki with zero per-seat cost and native metric charts. Confluence is the better choice for large organizations that need deep Jira integration, an established approval workflow, a mature plugin ecosystem, and enterprise support contracts. The comparison is not primarily about features but about deployment model; Confluence Data Center requires significant infrastructure and licensing overhead, while Oxynote is one container.
Quick start#
Oxynote runs as a single Docker container with a persistent data volume.
```bash
docker run -d --name oxynote \
-p 8080:8080 \
-v oxynote_data:/oxynote/data \
ghcr.io/oxynote/oxynote:latest
```What it's built on#
- Languages
- GoTypeScript
- Frameworks
- Nuxt
- Databases
- PostgreSQL
- Cache
- Redis
- Tooling
- esbuild
FAQ#
Does Oxynote replace Grafana?
Not yet fully. Oxynote covers metric charts and dashboard-style grids from Prometheus and SQL. Logs and alerting are not yet implemented, as the project FAQ states directly. For teams that primarily need a place to explain their metrics alongside the metrics themselves, Oxynote is a practical choice over Grafana plus a separate wiki. Teams that rely on Grafana's log ingestion, alert routing, or plugin ecosystem still need Grafana for those parts.
What data sources does Oxynote support for live metrics?
Prometheus for time series metrics, and SQL-based sources including PostgreSQL, MySQL, and MariaDB. Each Live Metrics block is configured with one or more queries against these sources. Additional data sources are not documented in the current README.
Does Oxynote require an external database to run?
No. The quick-start is a single Docker container with a volume mount for data. The README shows this as the complete setup without any separately provisioned database. For teams that want a self-hosted wiki without a Postgres or MySQL prerequisite, this reduces setup to pulling the image and running the container.
What is Oxynote's license?
Apache 2.0, a permissive license that allows running Oxynote on commercial infrastructure, modifying the source, and redistributing it without per-seat fees or commercial use restrictions. No additional terms extend or restrict the Apache 2.0 grant.
Can AI agents like Claude Code connect to Oxynote to read pages and run queries?
Yes. Oxynote exposes its tools over the Model Context Protocol. MCP-compatible clients including Claude Code and Codex connect via OAuth and can read pages, edit them, and run metric queries, the same capabilities available to the built-in Rubber Duck assistant. Teams building incident-response agents or automated operations workflows can point those agents at an Oxynote workspace.
Similar open-source tools#
Anytype
Local-first knowledge OS with E2E encryption and P2P sync
Outline
Team wiki and knowledge base with realtime collaboration
Typemill
Flat-file CMS: write Markdown, publish docs and user manuals
AppFlowy
Open source Notion alternative with AI, self-hosted
Docmost
Self-hosted collaborative wiki and documentation tool
Dendron
Local-first Markdown notes with hierarchy and backlinks