Baalda
Download
GuidesSelf-hostingReference

Introduction

What Baalda is, the problem it solves, and how plain Markdown files and a live CRDT stay true at the same time.

Baalda is a local-first desktop app for notes and knowledge. Every note is a plain .md file in a folder on your own disk, so your data stays yours and keeps working with Git, Finder, ripgrep and any editor you already use. What makes it different is that those same files are edited by your team in real time and read and written by your AI.

The problem it solves

A team that wants one shared, always-current context layer finds that every existing tool forces a choice. You can have notes as plain files an AI can edit, or real-time team collaboration, but not both. The reason is structural rather than a gap in the market.

  • AI-editable notes need loose Markdown on disk as the source of truth.
  • Real-time collaboration is built on CRDTs, whose state is an opaque binary blob.

41 open-source Obsidian-like apps were scanned against 12 core requirements and none satisfied all 12. Baalda is the bridge between those two worlds, and that bridge is the product.

How it works

The .md file on disk is the durable source of truth. A per-note Yjs Y.Text holding the raw Markdown string is the live source of truth while the note is open or syncing. A two-way bridge keeps them equal.

  • File to CRDT. The watcher sees a change on disk, the old and new text are diffed, and the difference is applied as operations in an origin-tagged transaction.
  • CRDT to file. A debounced update event serializes the text and writes it atomically, recording a lastWrittenHash so the watcher ignores the app's own write.

Both directions funnel into the same CRDT as operations rather than whole-file overwrites, so a person typing, a teammate across the world and an AI rewriting a paragraph merge instead of overwriting each other.

Everything except your files is rebuildable. The local search index, the CRDT history and the server's copy can all be deleted and derived again from the Markdown.

What is in the app

SurfaceWhat it is for
SidebarThe folder tree of the open vault, with sorting, right-click actions and access padlocks
EditorCodeMirror 6 over the raw Markdown, with properties, tabs, folding and in-place tables
Right panelBacklinks, outline and version history for the open note
Vault SettingsGeneral, Vaults, Members and access, MCP, Versioning, Import / Export, Appearance, and Billing when the server has billing on
Account menuSign in and out, switch vault, invitations, bug reports, check for updates

Where your notes sync

The desktop app is identical either way. It is the server URL that differs.

  • Managed. https://api.baalda.com handles multi-device sync, team collaboration and hosted features. Free for 2 people and 1 synced vault.
  • Your own server. One HTTP service plus Postgres, Apache-2.0, with no paid tier and no limits.
  • Local only. A vault that never leaves your disk, with no account at all.

Start here

QuickstartInstall the app, open a vault, invite someone, connect an AI.Core conceptsVault, note, docId, the bridge, shares and the registry, defined once.Connect an AILocal agents need no setup. Remote agents use the MCP endpoint.Self-host the serverDocker, Compose, Railway or Coolify, and the full configuration.

This page is written from README.md, docs/Baalda.md and docs/specs/00-architecture-overview.md in the repository. Those documents go further, and they are the ones that change first.

Read it on GitHub

Was this page helpful?

NextQuickstart