Skip to content
Back to search

oxynote

An open‑source technical wiki connected to the systems it describes

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/oxynote/oxynote with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/oxynote/oxynote'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/oxynote--oxynote/badge.svg)](/listings/oxynote--oxynote)

HTML

<a href="/listings/oxynote--oxynote"><img src="/api/listings/oxynote--oxynote/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Oxynote is one container. This is all it takes:

docker run -d --name oxynote \
  -p 8080:8080 \
  -v oxynote_data:/oxynote/data \
  ghcr.io/oxynote/oxynote:latest

Open http://localhost:8080 and log in with `admin@example.com` and `oxynote-admin-1234`.

To run from source, see [CONTRIBUTING.md](CONTRIBUTING.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 315 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # Oxynote
  3. **Your system, with subtitles.**
  4. A self-hosted workspace that puts live metric charts and logs inside the
  5. pages that explain them. They run your Prometheus, Loki and SQL queries,
  6. and a change to a page goes through a draft, a diff and an approval, like a
  7. pull request. From the authors of
  8. [ttlcache](https://github.com/jellydator/ttlcache).
  9. [![License](https://img.shields.io/github/license/oxynote/oxynote)](LICENSE)
  10. [![Release](https://img.shields.io/github/v/release/oxynote/oxynote)](https://github.com/oxynote/oxynote/releases)
  11. [![Discord](https://img.shields.io/discord/1559252157826469988?label=Discord&logo=discord&logoColor=white&color=5865F2)](https://discord.gg/mNJd5zJkvC)
  12. </div>
  13. <picture>
  14. <source media="(prefers-color-scheme: dark)" srcset="docs/images/logs-and-metrics-dark.webp">
  15. <img src="docs/images/logs-and-metrics-light.webp" alt="An Oxynote page called Deploy Watch: a paragraph on how a change moves from merge to production, then a Release pipeline log with error, warning and info rows beside a Latency during rollout chart with p50, p95 and p99 lines and an SLO threshold at 300 ms. The page tree and tags fill the sidebar.">
  16. </picture>
  17. ## Why Oxynote Exists
  18. Keeping a service running takes several tools. You read about it in a wiki
  19. such as Notion and watch its metric charts and logs in Grafana or Datadog,
  20. while the commands that fix it sit in a terminal history or a chat thread. When
  21. something breaks, you connect all of that by hand, across tools with
  22. separate logins and separate histories.
  23. Oxynote is a new kind of tool because it puts the explanation, the live
  24. metric charts and the logs on one page. Each chart or log block runs its
  25. own Prometheus, Loki or SQL query, and one draft carries a change to the
  26. block and its text through the same review.
  27. The goal is to watch and run the service from that same page. Its uptime
  28. monitor, a view into its database and its admin actions would sit next to
  29. the explanation, and changes to them would go through the same
  30. review. All of them are in development.
  31. <details>
  32. <summary>The long version is a bit of a rant, but it explains the <em>personal</em> why</summary>
  33. For a long time, the most reliable documentation at my company was the
  34. Slack chat I had with myself. How it got that way starts with
  35. metric charts. We had a lot of them: Grafana, Sentry, for some reason a bit
  36. of Datadog, and a few custom self-hosted HTML pages with charts on them.
  37. On top of that, I was encouraged to run my own health checks for the
  38. deployments I owned (why that could not live in Grafana or anything like
  39. it, nobody could tell me). Those deployments were services pulling
  40. financial market data over websockets. Under heavy volume they leaked
  41. memory and got OOM killed. There was a bug in there somewhere that we
  42. were chasing and could not find for a while, and in the meantime every
  43. kill meant missed events, and missed events meant running backfill
  44. scripts by hand. None of those charts showed any of that. So: cron, curl
  45. against each service's status endpoint, and the result posted to me
  46. privately on Slack. Not convenient at all.
  47. Then there was everything else. Internal wikis still describing
  48. deployment procedures for trial products that had ended. Secret vaults.
  49. Server management commands and curl requests. None of it lived in one
  50. place, and access was its own problem: each of these had a different
  51. owner who could grant it, so a lot of my time went into finding out who
  52. that was and then finding them. Since we talked on Slack, that is where
  53. I asked for all of it, and that is where people answered, sometimes with
  54. plain credentials (the horror). To not lose any of it, I forwarded those
  55. messages to the chat with myself, which is how that chat became my
  56. source of truth for a long time: links to the specific Grafana
  57. dashboards that mattered out of the many we had, example curl requests
  58. against other teams' services so I could match their responses when
  59. integrating (neither the requests nor the responses were documented
  60. anywhere), and server IPs with notes on what was deployed where.
  61. Naturally, I did try to fix it. I wrote Notion docs and linked the
  62. Grafana charts from them, and for a while that was fine. Then they
  63. drifted apart. One doc explained the labels on our ingestion-rate chart,
  64. market, region and so on, but new labels kept being added, nobody
  65. documented them, half were not even used in the chart, and each one cost
  66. Prometheus another time series. Keeping a doc and a chart in sync meant
  67. links on both sides, in Notion and in Grafana, which was more work than
  68. I wanted, plus switching browser tabs just to check that the explanation
  69. and the chart still meant the same thing. And that was only
  70. observability. Beyond it, admin actions were specific curl requests, and
  71. feature flags lived in a service disconnected from everything else. All
  72. of it deserved a proper review flow, like on GitHub, with diffs that work
  73. for text, metric charts and other visual structures. Instead it had
  74. none.
  75. David ([@davseby](https://github.com/davseby)), who started Oxynote with me
  76. ([@swithek](https://github.com/swithek)), was the one who had to work
  77. through a system and its documents the first time he was on call, at a
  78. different company. He had years of Grafana and internal docs behind him and
  79. expected it to be routine. What he got was Datadog, which he had never used,
  80. and a wildly different Notion structure. Then, on that first shift, the
  81. services that enrich image metadata failed. Search over user uploads turned
  82. inaccurate, and from there it cascaded through the product. Monitors fired,
  83. but none of them linked anywhere or said which service had started failing,
  84. which made for a nerve-racking night of tying things together by hand. The
  85. metric showing one service overloaded and unresponsive existed the whole
  86. time. Datadog's UI is convoluted, though, and nothing explained what any
  87. chart tracked, so David never found it. An AI agent connected to Datadog's
  88. MCP server did.
  89. What both of us wanted was the metric chart, the explanation, the command
  90. and the flag on one page, edited together, reviewed like a pull request,
  91. and readable by a tired person at night or by an agent. Each tool we had
  92. was great at one of those things and paid little attention to the others.
  93. So Oxynote starts with the pieces we needed most: pages people edit
  94. together, live metric charts and logs, reviews and Stripe-style API docs. Uptime
  95. monitors, AI evals, a database viewer and admin actions are in
  96. development.
  97. </details>
  98. ## Quick Start
  99. Oxynote is one container. Start it with Docker:
  100. ```sh
  101. docker run -d -p 8080:8080 \
  102. -v oxynote_data:/oxynote/data \
  103. ghcr.io/oxynote/oxynote
  104. ```
  105. Open http://localhost:8080 and sign in as `admin@example.com` with the
  106. password `oxynote-admin-1234`. The login page shows both until you change
  107. the password, so change it in the settings before anyone else can reach the
  108. instance.
  109. The [self-hosting guide](https://oxynote.io/blog/self-host-oxynote) walks
  110. through the install and the steps after it: Docker Compose, another port or
  111. domain, a first page with a metric chart, backups and upgrades. To run
  112. from source, see [CONTRIBUTING.md](CONTRIBUTING.md).
  113. ## Features
  114. Oxynote keeps the pages about your systems, such as architecture notes, API
  115. references, on-call steps and release checklists, in one page tree. Those
  116. pages can query Prometheus, Loki, PostgreSQL, Supabase, MySQL or MariaDB,
  117. so the live metrics and logs sit right where you write about them.
  118. ### Live Metric Charts
  119. <picture>
  120. <source media="(prefers-color-scheme: dark)" srcset="docs/images/chart-editor-dark.webp">
  121. <img src="docs/images/chart-editor-light.webp" alt="The Live Metrics editor: a Hotfixes per release bar chart redrawn above its PromQL query, which uses $__rate_interval and a $hotfix_budget variable. On the right, the chart type, the Prometheus data source, the unit and an Over budget threshold at 100.">
  122. </picture>
  123. A Live Metrics block draws a time series, a bar chart or a gauge from one
  124. or more PromQL or SQL queries, and the editor redraws it as you type.
  125. Thresholds and units sit next to the query. Grafana macros such as
  126. `$__rate_interval` and `$__timeFilter` work too, so a query you already
  127. use there usually moves over with a paste.
  128. No metric yet? Pick a pattern such as latency or error rate, and the chart
  129. draws simulated data until the real series arrives. SQL sources need a
  130. read-only database user, so a page can never change your data.
  131. To connect your own metric data source, follow the
  132. [Prometheus guide](https://oxynote.io/blog/connect-prometheus) or the
  133. [PostgreSQL guide](https://oxynote.io/blog/connect-postgresql).
  134. ### Live Logs
  135. <picture>
  136. <source media="(prefers-color-scheme: dark)" srcset="docs/images/logs-dark.webp">
  137. <img src="docs/images/logs-light.webp" alt="A Live Logs block titled Findings and merges: a volume strip of stacked bars across the time range, then secret scanner and pull request logs with warning, info and error levels. One error log is open, showing its raw text and its origin, metadata and content fields, each with buttons to show only or hide logs with that value.">
  138. </picture>
  139. A Live Logs block runs one or more queries against a log source and lists
  140. the newest logs, each level in its own color. A volume strip above
  141. them shows how many logs arrived across the time range, so a sudden spike
  142. is easy to spot.
  143. Click a log to open its raw text and fields. One more click on a field
  144. keeps only the logs with that value, or hides them, and the query stays as
  145. you wrote it.
  146. To connect your own logs, follow the
  147. [Loki guide](https://oxynote.io/blog/connect-loki).
  148. ### Variables
  149. <picture>
  150. <source media="(prefers-color-scheme: dark)" srcset="docs/images/dashboard-dark.webp">
  151. <img src="docs/images/dashboard-light.webp" alt="The Variables panel open beside a page of live metric charts. The built-in metric time range is set to the last 6 hours, and an Engineering group holds a hotfix budget of 2. The page shows a review turnaround line chart, a deploy confidence gauge and a hotfixes per release bar chart.">
  152. </picture>
  153. Variables are defined once for the whole workspace, and any query on any
  154. page can read them. `$metric_range` comes built in: set it to the last six
  155. hours, and each chart that uses it shows the last six hours from then on.
  156. The values you pick apply only to you, so they change your charts and
  157. nobody else's.
  158. ### Blocks
  159. <picture>
  160. <source media="(prefers-color-scheme: dark)" srcset="docs/images/slash-command-dark.webp">
  161. <img src="docs/images/slash-command-light.webp" alt="The block menu open under a slash on an Oxynote page, listing headings, lists, a checklist, a code block, a callout, an image, a file, a Figma embed, a divider, a Mermaid diagram, Split Documentation and Live Metrics, each with its Markdown shortcut.">
  162. </picture>
  163. Type `/` for the block menu: headings, lists, checklists, code, callouts,
  164. images, files, Figma embeds, Mermaid diagrams, Stripe-style API docs, live
  165. metrics and live logs. Markdown shortcuts such as `##` work as you type. Two go
  166. further: `%%` adds a live metric chart, and `||` starts an API doc with the
  167. fields on one side and an example request on the other.
  168. ### Search
  169. <picture>
  170. <source media="(prefers-color-scheme: dark)" srcset="docs/images/search-box-dark.webp">
  171. <img src="docs/images/search-box-light.webp" alt="Search results for “feed”, grouped by page: a time series chart title, two paragraphs and a Bash snippet from one page, then matches on two more pages. The footer counts 14 matches on 8 pages.">
  172. </picture>
  173. `⌘K` searches the whole workspace, down to a single line in a code block or
  174. a diagram's source. Results come grouped by page, and each one says what it
  175. matched, such as a Bash snippet or a time series chart. Typos are fine too.
  176. ### Reviews
  177. <picture>
  178. <source media="(prefers-color-scheme: dark)" srcset="docs/images/review-dark.webp">
  179. <img src="docs/images/review-light.webp" alt="A draft of the Tracking API page with Show Changes on: removed text in red and added text in green across the intro, a new callout, an endpoint path, a path parameter and its JSON response. A Merge Draft into Main button, the maintainers and an approving reviewer sit in the header.">
  180. </picture>
  181. Make a page reviewable, and its main branch stops taking direct edits.
  182. Changes go into a draft branch instead. The diff works on blocks, so a
  183. renamed API parameter and a moved chart threshold show up in red and green
  184. right where they sit.
  185. Reviewers approve the draft on the page itself. Merging is a separate step,
  186. so an approved draft can wait until the change it describes goes live.
  187. ### Collaboration
  188. <picture>
  189. <source media="(prefers-color-scheme: dark)" srcset="docs/images/collaboration-dark.webp">
  190. <img src="docs/images/collaboration-light.webp" alt="Two people on a 2027 roadmap page at once, their named cursors on a sentence and on a Gantt chart. A comment thread on “arrival above 92 percent” is open, with a question, a reply and an unsent answer in the reply box.">
  191. </picture>
  192. Everyone on a page shows up as a named cursor, along with the block they're
  193. holding, and edits from several people merge as they type. Comments attach
  194. to a single word or a whole block. New comments and replies land in your
  195. inbox, and one click there opens the block they're on.
  196. ### Agents and MCP
  197. <picture>
  198. <source media="(prefers-color-scheme: dark)" srcset="docs/images/mcp-dark.webp">
  199. <img src="docs/images/mcp-light.webp" alt="Claude Code in a terminal over an Oxynote page, with a prompt asking it to add a failed bookings chart with a threshold at 2%. The page already shows that chart under the position feed latency chart.">
  200. </picture>
  201. Oxynote is designed for people first, and agents get an interface of their
  202. own. Claude Code, Codex and many other MCP clients connect once you approve
  203. them. They read each page as structured blocks and change only the blocks
  204. they need. Their edits appear live, and on a reviewable page they wait in a
  205. draft until a person approves them.
  206. Rubber Duck, the built-in assistant, does the same inside the app. It runs
  207. on a model from Anthropic, OpenAI, Google or OpenRouter, or a local one
  208. through Ollama. Both stay optional: the assistant is off until you set it
  209. up, as [docs/ai.md](docs/ai.md) describes, and the rest of Oxynote works
  210. without either.
  211. ## Simple on Purpose
  212. Oxynote has few settings, on purpose. Each job has one way to get done,
  213. with defaults that already fit, so there is less to learn. The rest of the
  214. design follows from a few fixed choices:
  215. - Protected pages change only through approved drafts, so each change
  216. carries a diff and the name of whoever approved it.
  217. - Only people you invite can open your workspace, and an AI agent gets in
  218. only after you approve it.
  219. - A page can depend on things outside Oxynote, such as a config file in
  220. your repository, the container image you deploy or a vendor's API docs.
  221. An optional freshness hook watches each one, and when it changes, the
  222. page's maintainers get a reminder to update the parts that rely on it.
  223. - The code is Apache-2.0 licensed and developed in public.
  224. - Oxynote runs as one container on your own servers, so your data and your
  225. upgrade schedule stay with you.
  226. ## In Development
  227. The goal is one place to explain, watch and run your systems. Uptime
  228. monitors, AI evals, a database viewer and admin actions are in development,
  229. along with traces and alerting.
  230. ## FAQ
  231. **Can it replace Grafana or Datadog?** That is the goal. Metric charts and
  232. logs are covered today: Oxynote runs your Prometheus, Loki and SQL queries
  233. inside pages you can write around and review like a pull request. Traces
  234. and alerting are in development.
  235. **Is there a cloud version?** Not yet. A cloud version is planned, and
  236. today Oxynote runs as one container on your own servers.
  237. **Do I need AI to use it?** No. The assistant stays off until you set it
  238. up, and the MCP server is optional too.
  239. **Is it worth using by myself?** Yes. A workspace works fine with one
  240. person, and when you do invite others, a self-hosted install has no member
  241. limit.
  242. **Why the name?** In the beginning, Oxynote was called "breathing docs".
  243. Breathing needs oxygen, so "oxy" became the prefix and "note" followed.
  244. ## Community
  245. Ask questions on [Discord](https://discord.gg/mNJd5zJkvC), where the people
  246. building Oxynote answer them. For a bug or an idea,
  247. [open an issue](https://github.com/oxynote/oxynote/issues). To report a
  248. vulnerability, follow [SECURITY.md](SECURITY.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.