Basalt documentation
Basalt is a knowledge workspace: block-based documents, typed databases with views, and real-time collaboration — Markdown-native, API-first, and self-hostable as two containers.
The idea it is built around: every block has exactly one canonical home, and can be referenced — live and editable — anywhere else. One truth, many references.
Run it
- Self-hosting — clone,
docker compose up, register. Start here. - Configuration — every environment variable, what it does, and whether the shipped compose file actually delivers it.
- Operations — reverse proxy and TLS, backups, upgrades, closing registration, monitoring (probes, metrics, the three alerts worth having), troubleshooting.
Build on it
- API — authentication, access tokens, errors, pagination, webhooks, and pages as Markdown.
- API reference — every endpoint, generated from the OpenAPI document the server emits.
- Markdown specification — the canonical dialect every page serializes to and parses back from, loss-free.
- MCP server — the first-party Model Context Protocol server, for agents.
Work on it
- Development environment — DDEV, pnpm, Turborepo, the test suites.
- Architecture — what the system is made of and why.
The decision log — architecture decision records, the data model, the sync
design, the roadmap — lives in
docs/architecture/
in the repository. It records how things were decided, including the
alternatives that were rejected; it is written for people changing Basalt, not
for people using it.
What state is this in?
Pre-1.0 and moving. Documents, references, databases, permissions, comments, history, import/export, public shares, access tokens and webhooks all exist and work. There is no released Docker image, no email of any kind (so no password reset and no invitation mail), and the licence is not final.
Where a guide here describes something that does not work yet, it says so on the page rather than leaving you to find out.