NotusBase guide
For people building a system on top of NotusBase without reading the server code. Written from what was actually executed, with the convex 1.49.0 package and TypeScript 7.0.2, and revised on 2026-11-12 against the binary, by following it from an empty machine.
NotusBase 0.1, 0.2 and 0.3 are pre-releases, not meant for production: a version may remove or rename something with no transition. 0.4 is the first stable version.
| Guide | What it is for |
|---|---|
| Rules | A single page for whoever writes a system, human or AI: project, modeling, access, errors, secrets, limits, how to test and the development MCP. Start here |
| 1. Quick start | From notusbase init to a project with a table, two functions, login and a test, with no Go and no C compiler |
| 2. Migrating from Convex | What changes, what does not exist, what behaves differently |
| 3. Data modeling for products | tenantId, one transaction per group, files and logs, SQL and reports, and changing the schema with data |
| 4. Limits per function | Time, memory, reads, writes, sizes, with the numbers from the code |
| 5. First server | From the Linux package to a system online: systemd with its own HTTPS, a setup page in the browser (account, origins, S3 backup, email, deploy key, checks) and the deploy, in 5 commands |
| 6. Operations | Keeping the server running: check, update with rollback, backup and restore, rehearse a deploy, metrics and alerts, the dashboard and the second factor, why it is slow, capacity |
| 7. Runbooks | One section per warning of the dashboard and alert of alerts.yml: what it means, how to confirm it and the fix, command by command. Each warning links to its section |
| Client certificates | Mutual TLS in fetch and signed XML with the company's A1 certificate, for banks and government APIs |
| Reference | Every command and flag, every name a function can call, every export of the modules and of the test kit, and every variable, generated from the code. The examples in it run as a test |
| Example project | Order manager with login, files, scheduling and tenantId, with an end-to-end test |
On one page
- What it is: TypeScript functions in the Convex format (
query,mutation,action,httpAction, scheduler, crons, files, search) running in V8 inside a PocketBase server, with SQLite. The client is theconvexpackage, unchanged. One binary, one database per process. - What it is for: products owned by the server's own operator, split by customer or team. It is not a BaaS: there are no developer accounts and no multiple projects per server.
- Status: version 0.3, a pre-release. It has never run with real traffic. Before exposing it to the internet, give it a domain, so it does its own HTTPS, or put a proxy with TLS in front, and turn the backup on: First server.
- Two rules that apply from day one:
tenantIdon every data table and as the first column of every index.- A transaction never crosses two groups. What crosses groups becomes an idempotent job.