What Cloud Codex is, in our own words.

Archive engineeringLast edited 4 minutes agoHistory 3 revisionsEditors 3Merge CRDT

This is a real note out of our own workspace, opened to the public. It is not a page about the product written by somebody in marketing; it is the page the three of us keep for ourselves, which is why there are unresolved arguments in the margin.

Cloud Codex is where a team writes documentation together, in real time, on hardware you own. Two people can type in the same paragraph and neither loses a word. It has GitHub inside it rather than beside it. It is source-available, so the claims on this page can be checked against the code that makes them, which is the only reason we are comfortable making them.

Everybody can be in the same paragraph

Every document is a conflict-free replicated data type. When your edit and somebody else's edit land in the same sentence, the result is defined by the data structure rather than decided by who arrived last. There is no last-write-wins, no locked section, and no dialog asking which version to keep. Those three are what people mean when they say a wiki does not really do real-time.

Your keystrokes apply locally first, so typing does not stutter when the connection does. They coalesce into one binary write every 3000 ms, which is why a fast typist and a slow one cost the database the same. The readable copy that search and exports are built from is written when somebody saves. That split isa known tradeoffdeliberate, not a race, and the section further down says what it costs.

GitHub is in the room, not on a webhook

Almost every documentation tool means the same thing by “GitHub integration”: a webhook, a queue, a worker, and a mirror of your repository in their database being wrong by a few minutes. We hold no copy. Every call is live and made with your own OAuth token, at the moment you look at something.

Browse the tree, open a file and edit it here with a real commit, manage branches, open and review pull requests. Embed a block of code into a note and it stays pinned to a revision, so the quote in your document is the quote you meant rather than whatever that file happens to say next year.

Who can read this is one question, asked once

Workspaces own squads, squads own archives, archives own documents. There are 7 ways to be allowed into an archive, and they are not 7 trips to the database.

They are one SQL fragment with 7 branches, evaluated inside the query that was going to fetch the rows anyway, which is why permission checks do not get slower as your workspace fills up. The rows you may not see are never in the result to begin with. That is also why the 2 archives you cannot open are listed as ungranted rather than shown to you greyed out: we cannot list what you are not allowed to know exists.

It runs on two things

One Node process holding the API, both WebSocket servers and the built front end, and one MySQL 8 container. That is the entire production compose file. No message broker, no Redis, no search cluster, no background job queue, no telemetry endpoint, and no licence server to phone home to us.

Being precise, because a short parts list is easy to overstate: it is an ordinary Node application with an npm dependency tree, the GitHub surface makes live calls to GitHub when you ask it to, and notification email goes out through an SMTP server you name or not at all. What there is none of is anything reporting back to us.

What it costs

Live collaboration state lives in memory in that single Node process. That is exactly what lets the whole system be two containers with nothing to operate between them, and it is also the ceiling: you cannot run a second copy behind a load balancer, because each would hold its own divergent copy of the same open document.

There is a second one. Because the debounced write persists the binary state only, a document a team has been editing over the socket for an hour without saving is entirely current for everybody in it and an hour stale to full-text search. Both of these are things we would rather you read here than discover in month four.

What it will not do

There is no public signup: an administrator issues invite tokens, which is the right default for a company's internal documentation and the wrong one for a public wiki. There is no anonymous read, so every reader is a known account. There is no hosted tier: you run it, we will help you stand it up and build on top of it, but there is no server of ours holding your documents.