# Introduction

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

Source: https://baalda.com/docs/introduction
Site: Baalda, https://baalda.com

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

| Surface | What it is for |
|---|---|
| Sidebar | The folder tree of the open vault, with sorting, right-click actions and access padlocks |
| Editor | CodeMirror 6 over the raw Markdown, with properties, tabs, folding and in-place tables |
| Right panel | Backlinks, outline and version history for the open note |
| Vault Settings | General, Vaults, Members and access, MCP, Versioning, Import / Export, Appearance, and Billing when the server has billing on |
| Account menu | Sign 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

- [Quickstart](/docs/quickstart): Install the app, open a vault, invite someone, connect an AI.
- [Core concepts](/docs/concepts): Vault, note, docId, the bridge, shares and the registry, defined once.
- [Connect an AI](/docs/ai-overview): Local agents need no setup. Remote agents use the MCP endpoint.
- [Self-host the server](/docs/deploy): Docker, Compose, Railway or Coolify, and the full configuration.