Documentation
Baalda documentation
A second brain your team edits together and your AI can edit too, from plain Markdown files on your own disk. These pages cover the desktop app, sharing a vault, the MCP endpoint, running the server yourself, and the architecture underneath. Written against version 0.1.82.
Guides
- IntroductionWhat Baalda is, the problem it solves, and how plain Markdown files and a live CRDT stay true at the same time.
- QuickstartInstall the app, open your first vault, choose where it syncs, invite a teammate, and point an AI at it.
- Core conceptsThe vocabulary: vault, note, docId, revision, the bridge, the registry, shares, sync tokens and recovery copies.
- VaultsWhat a vault is on disk, local-only against synced, switching and leaving, and the two recovery paths when a folder goes missing.
- The editorMarkdown that reads as a page, properties with real types, in-place tables, tabs, and the appearance settings that shape them.
- Search, links and tagsThe local index: full-text search, backlinks that survive a rename, tags, and how the sidebar is sorted.
- Attachments and filesWhich file types open, embed and search, the size ceilings, and the difference between embedded attachments and standalone file sync.
- Versions and recoveryVersion history, the version kept before a large deletion, the server's 30-day Trash, recovery copies, and restoring damaged notes.
- Members and rolesInviting people by email or join code, what each role may do, and the roster, profiles and activity behind a vault.
- Access controlThe three controls that decide who sees what, how grants combine, and what a restriction does to the files already on someone's disk.
- Sync and offlineThe two channels, what the sync indicator means, what happens after time offline, and when a server is behind the app.
- Presence and voiceLive cursors, who is in a note, online status, and the hold-to-talk broadcast that is never recorded.
- AI overviewTwo ways an agent works a vault: directly on the files when it can reach your disk, and over MCP when it cannot.
- Connect an AI over MCPCreate a token, register the endpoint, and connect Claude Code, a custom connector or any MCP client.
Self-hosting
- Deploy the serverWhat the server is, the one port it needs, and four ways to run it: Docker, Compose, Railway or Coolify.
- ConfigurationThe environment variables the server reads: the required three, then sync, batching, storage, email, billing and scale.
- Attachment storageKeep attachment bytes in Postgres, or move them to S3-compatible storage, with garbage collection and a verified migration.
- Outbound emailWhat switches on when you configure a transport, what happens when you do not, and which transports are accepted.
- Scaling and operationsWhat one instance handles, what Redis buys you, how upgrades and staging work, and what to back up.
- Connect the app to your serverHow the desktop app chooses a server, the one-link invitation path, and the URL rules packaged builds enforce.
- Build from sourcePrerequisites, then the commands that bring up the server and the desktop app from the repository.
Reference
- MCP tool referenceAll 22 tools the MCP endpoint exposes, with their parameters, their defaults and what refuses a call.
- Settings referenceEvery tab in Vault Settings and what it controls, plus what the account menu carries.
- ArchitectureThe four pillars, the two join keys, the three stores on a client, and the specification set behind each.
- Plans and limitsSelf-hosting is free and unlimited. On the managed backend, what Free includes, what Team adds, and what a lapsed plan does.
- TroubleshootingThe problems that actually come up: a server behind the app, a missing folder, notes that will not sync, and uploads that fail in the client.
- Security and privacyWhat travels the network, where credentials are kept, how access is enforced, and how to report a vulnerability.
- Releases, licence and contributingHow versions ship and update themselves, where the changelog lives, what the licence allows, and how to contribute.
In the repository
The specifications, the interaction inventory, the release process and the changelog live with the code, so they change in the same commit it does. Each page here links to the document it was written from.