Baalda

Baalda is a local-first desktop app for notes and knowledge: your second brain. Every note is a plain .md file on your own disk, so your data is always yours. What makes Baalda different is that those same files are:

• Editable by AI. Because notes are plain files, a local agent like Claude Code edits them right on your disk with zero setup. Cloud and autonomous agents connect through the built-in MCP endpoint. Either way, the AI works your notes like a teammate would.
• Shared in real time. Invite people, share a folder, and edit the same note together with live cursors.

You get the openness of local Markdown files and the collaboration of a shared doc, in one app.

AI is only as good as the context you give it. A team that wants one shared, always-current context layer quickly discovers that every existing tool forces a choice:

Why? The two are built on incompatible foundations. 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. No tool combined them.

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

• 📄 Your notes are just files. Plain .md on disk. No lock-in, works with Git, and survives even if the server disappears.
• 🤖 AI-editable, two ways. Local-first means a local agent (Claude Code, Codex, any CLI tool) edits the .md files directly, no integration needed. Autonomous and cloud agents use the built-in MCP endpoint, gated by the exact same permissions as a human. Both paths merge live with everyone else's edits.
• 👥 Real-time collaboration. Invite teammates and edit together with live cursors. Notes are private by default — share a folder or single file with the whole team or one person (view or edit), and folders/renames/moves sync live too.
• 🔒 Local-first and private. A full desktop app that works offline. Your Markdown never travels the network in plain text; only opaque binary sync updates do, and each device re-derives its own .md files.
• 🔎 Fast search and links. Built-in full-text search (SQLite FTS5), backlinks, and tags, all indexed locally.
• 🖥️ Native and cross-platform. A lightweight Tauri v2 app for macOS, Windows, and Linux (iOS planned).
• 🛠️ Self-hostable. Runs entirely on your own infrastructure (Tauri + Node + Postgres). No vendor lock-in.
• 📎 Attachments included. Images and files sync alongside your notes.

Baalda is built to grow with you, from a personal vault to a whole company:

Need more? It scales out to handle tens of thousands of people at once.

The core idea in one sentence: the .md file on disk is the durable source of truth, and a live CRDT keeps every open copy in sync.

• When you (or an AI) change a file, a watcher turns the change into CRDT operations.
• When a teammate edits the shared note, those operations flow back and are written to your file.

Every change funnels through the same CRDT as operations, never whole-file overwrites. Whether it comes from a person typing, an AI rewriting a paragraph, or a teammate across the world, edits merge instead of overwriting each other.

Everything else (the desktop app, the search index, the sync server) is a rebuildable layer on top of your files.

• Node.js ≥ 22 (with corepack: corepack enable activates the pinned pnpm)
• Rust & Cargo (rustup.rs)
• Docker (for the Postgres database)

cd app
pnpm install

cd apps/server
cp .env.example .env # adjust JWT_SECRET for anything real
pnpm run db:up # start Postgres in Docker (host port 5439)
pnpm run migrate # create the database schema
pnpm run dev # HTTP API :3010 · sync WS at :3010/sync (a legacy dedicated :3011 also listens)

From the app/ directory:

pnpm run dev:desktop # launches the Tauri app (Vite on :1420)

Open a folder of Markdown files (or create a new one) and start writing.

Everything above is self-hosted and free. If you'd rather skip the backend ops, baalda.com offers a managed backend for multi-device sync, real-time team collaboration, and hosted AI. The desktop app is identical either way: in Settings, set the server URL to https://api.baalda.com (managed) or to your own instance.

To run a server for your team without managing machines, deploy one to Railway in a click — it provisions Postgres, generates its own signing secret, runs the migrations and gives you an HTTPS URL:

Deploy on Railway

The desktop app asks whether your notes live on the managed service or your own server before your first sign-in — put that URL there, or send your team https://<your-server>/open/connect and let them click it. See docs/DEPLOY.md for details.

Prefer your own machine? The Compose bundle brings up the same stack in one command:

cd deploy/compose
cp .env.example .env # fill in POSTGRES_PASSWORD, JWT_SECRET, BETTER_AUTH_URL
docker compose up -d

See deploy/compose/README.md for TLS, backups and upgrades, or docs/DEPLOY.md for plain Docker and the full environment variable reference.

A local agent needs no setup at all: point Claude Code (or any tool) at your vault folder and it edits the .md files directly. The watcher picks up every change and syncs it live to your team.

For cloud and autonomous agents that can't reach your disk, Baalda exposes a Model Context Protocol endpoint, so any MCP-speaking AI client can work with your vault exactly like a person, limited by the same per-folder permissions.

1. In the app, go to Vault settings → MCP and create a token.
2. Register the endpoint with your AI client, e.g. Claude Code:

claude mcp add --transport http context http://localhost:3010/api/mcp \
 --header "Authorization: Bearer mcp_..."

(On the managed service the endpoint is https://api.baalda.com/api/mcp; for a self-hosted server, use your server URL plus /api/mcp.)

The AI can now read_note, search_notes, create_note, edit_note (targeted replace/insert/delete at exact anchors), update_note, and more. read_note returns a revision; pass it back as expectedRevision and a write against a note that changed in between is refused instead of merged. Its writes flow through the same sync engine, so if the note is open you'll watch the AI type in real time.

app/
├── apps/desktop/ Tauri v2 app: Rust core (src-tauri/) + React/Vite/TS UI (src/)
└── apps/server/ Node/TS: Hono HTTP + Hocuspocus sync + Postgres + Better Auth + MCP
docs/ Product overview, build status, specs, and reference research

Deep dives live in docs/: the product overview, the design specs, and the build status.

Issues and pull requests are welcome. If you're planning a larger change, please open an issue first to discuss it. Read the design docs in docs/ to understand the architecture before diving in.

Baalda is open source under the Apache License 2.0 . Use it, self-host it, modify it, and build commercial products on it, freely.

The Baalda name and brand are trademarks and are not covered by the code license; see the Trademark Policy. You're welcome to fork and run the code; please give your version its own name.

Contributions are welcome under the same license, with no CLA required. See CONTRIBUTING.md, and report vulnerabilities via SECURITY.md.

One exception: the ee/ directory holds future commercial-only features under a separate Enterprise License. Everything else, the entire core, is Apache-2.0.