Tolaria: a git-first markdown vault app for macOS, Windows and Linux

What Tolaria actually manages, and who it is for

Tolaria is a desktop application for macOS, Windows and Linux whose stated purpose is managing markdown knowledge bases. The README lists three audiences: people running second brains and personal knowledge, teams organizing company documents as context for AI, and users storing assistant memory and procedures. The author, Luca Ronin, writes that he uses it on a workspace of more than 10,000 notes drawn from his Refactoring work plus personal journaling.

That last detail is the useful one. This is not a general note app aimed at someone with forty notes. The design decisions in the README, particularly keyboard-first editing and a command palette, assume a vault large enough that navigation is the hard problem. The principles section is explicit that Tolaria is aimed at power users who want to use the keyboard as much as possible.

The second audience is more interesting than it first looks. Organizing company docs as context for AI means the vault is meant to be read by agents, not only by humans, and the README names Claude Code, Codex CLI and Gemini CLI setup paths plus an AGENTS file for agents to read. If your team already points coding agents at a repository, Tolaria is arguing that the same repository can hold the prose those agents need.

Files-first, git-first: the mechanism behind the app

The architecture claim is simple and worth taking literally. Notes are plain markdown files with YAML frontmatter, and every vault is a git repository. There is no export step because there is no import step: the app reads and writes the files you already have.

That choice has consequences the README spells out. Version history comes from git rather than from an internal database, so any git remote works and there is no dependency on Tolaria servers. The README states there are no accounts, no subscriptions and no cloud dependencies, and that the vault works offline. If you stop using Tolaria, the README's phrasing is that you lose nothing, which is a claim about file format rather than about features.

The types system is where the design gets opinionated in a way that will divide people. Types are described as lenses, not schemas: navigation aids with no required fields and no validation. Anyone who has used a tool that enforces frontmatter fields will notice the absence. You get categories for finding notes; you do not get a guarantee that a note of a given type has the fields you expect. For a personal vault that is a reasonable trade. For a shared company vault where a script consumes the frontmatter, it means validation has to live somewhere else.

The stack is Tauri, React and TypeScript, with the repository layout confirming a src-tauri directory alongside src, an mcp-server directory, a site directory for the public docs published to GitHub Pages, and a demo-vault-v2 directory.

Installing Tolaria on macOS with Homebrew

The README gives a Homebrew cask as the macOS path. The command is a single line and installs the packaged desktop app rather than a development build.

brew install --cask tolaria

After it finishes, Tolaria should appear as a normal application. The README does not describe what the cask does beyond installing the app, and it does not document an uninstall command, so treat removal as a standard Homebrew cask uninstall rather than something the project documents.

On Windows and Linux the README points at the download page for the latest release instead of a package manager. One detail matters for managed machines: Windows installers are Authenticode-signed, but the README warns that company-managed devices may still require IT approval of the Tolaria publisher before first install. That is a policy step, not a technical failure, and it is worth knowing before you promise a rollout date.

First launch: cloning the getting started vault

On first open, the README says you are offered the chance to clone the getting started vault, which is a separate repository that walks through the app. That is the fastest way to see how a vault is structured before you point Tolaria at your own notes.

The public user documentation lives in the site directory and is published to GitHub Pages. The README names two entry points in order: Install Tolaria, then First Launch. Following those two pages before touching a real vault is the sensible sequence, because the app's behaviour depends on the vault being a git repository.

If you would rather build from source, the prerequisites are Node.js 20 or newer, pnpm 8 or newer, and Rust stable, with macOS or Linux listed for development. The quick start is two commands.

pnpm install
pnpm dev

That serves a browser-based mock mode at http://localhost:5173. The native desktop window comes from a different command.

pnpm tauri dev

Linux needs system libraries first, and the README gives per-distribution commands for Arch, Debian and Ubuntu 22.04 or newer, and Fedora 38 or newer. It also notes that the bundled MCP server spawns the system node binary at runtime on Linux, so Node has to be installed from your distribution's package manager if you want the external AI tooling flow to work. That is a real constraint on a machine where Node is only present through a version manager.

Where Tolaria is the wrong choice

The README is unusually clear about what Tolaria does not do, and the limits follow from its own principles rather than from missing features.

There is no cloud. No accounts, no subscriptions, no server component. If you want a vault that syncs between devices without you configuring a git remote, Tolaria is not that product, and the offline-first principle means it will not become that product. Git remotes are the sync mechanism, which also means conflict resolution is git's problem, not the app's.

There is no schema enforcement. Types have no required fields and no validation. A team that wants every meeting note to carry a date and an attendee list will not get that from Tolaria, and the README presents this as a deliberate position rather than a gap.

There is no documented rollback story. The README does not document rollback, migration between Tolaria versions, or what happens to a vault when a release changes how frontmatter is written. Since the vault is a git repository you can recover with git, but that is an inference from the git-first principle, not something the project documents.

The licence is another practical limit for some organisations. The package metadata records AGPL-3.0-or-later and the README says AGPL-3.0. Any team that intends to embed Tolaria in a product or modify it for distribution needs to read the licence text themselves; this article is not legal advice. For internal use of the desktop app the licence is unlikely to be the deciding factor, but for a fork it very well might be.

How Tolaria differs from Obsidian

The closest comparison people search for is Tolaria versus Obsidian, and the difference is not the editor. Both put markdown files on your disk. The divergence is in where structure lives.

Obsidian's model centres on a vault plus a plugin ecosystem, and its sync and publishing features are separate products. Tolaria's model centres on the vault being a git repository from the start, with git as the versioning and remote story, and the README states there is no dependency on Tolaria servers. If you already think in commits and remotes, Tolaria's vocabulary will match your habits. If you think in plugins, it will not, and the README does not describe a plugin system.

The second difference is the AI framing. Tolaria ships an mcp-server directory and an AGENTS file, and the README names Claude Code, Codex CLI and Gemini CLI setup paths while saying you can edit the vault with any AI you want. Obsidian's AI story is largely third-party plugins. For someone building a vault specifically as retrieval context for a coding agent, Tolaria's positioning is more direct, though the README does not document what the MCP server exposes, so that difference is a direction rather than a verified capability list.

Maintenance, releases and what an upgrade costs

The repository is not archived, and the last push was on 2026-08-28, which is recent enough that the project is being changed rather than parked. The release list shows something a new user should understand before they pick a download: on 2026-08-28 the project published v2027-08-28, and the same day it published alpha-v2027.8.30-alpha.0001 and alpha-v2026.8.28-alpha.0006. Two of the three artefacts from that day are alpha builds.

The version strings are also worth reading carefully. The dated release is named v2027-08-28 and the alpha builds carry 2027.8.30 and 2026.8.28 style numbers. Anyone scripting a download should match on the exact tag rather than on a date pattern, because the tags do not sort the way a calendar would suggest.

Upgrade cost is where the files-first design pays off and where it does not. Because notes are plain markdown with YAML frontmatter, moving between app versions does not require an export or import cycle, and a bad release can be answered by checking out the previous commit in the vault. What the repository does not document is a downgrade path for the application itself, or a compatibility matrix between app versions and frontmatter written by older versions. The package.json shows a version field of 0.1.0 while releases are tagged with dates, so the internal version number tells you nothing about which release you are running. Check the tag, not the package version.

The licence carries an upgrade-adjacent cost too. AGPL-3.0-or-later means a modified version distributed to others carries source obligations. For a team that only installs the app, this is a footnote. For a team that wants to ship a custom build internally to other legal entities, it is a question for counsel rather than for the README.

Editorial conclusion

Adopt Tolaria if you already keep notes as markdown files and want git history plus a keyboard-driven editor over them, and if you are comfortable with an AGPL-3.0 desktop application. Skip it if you need hosted multi-user sync, enforced note schemas, or a managed service, because the README states there are no accounts, no subscriptions and no cloud dependencies. Before committing a real vault, verify three things yourself: that your vault directory is a git repository as the git-first principle requires, that the bundled MCP server finds a system node binary on your Linux install, and that the release you download is the one you intend, given that the project publishes both a dated release and alpha builds on the same day.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes