How to Install Tolaria: Complete Setup Guide for macOS, Windows, and Linux

Install Tolaria on macOS using brew install --cask tolaria, download platform-specific binaries for Windows and Linux from the GitHub releases page, or compile the application from source using Node.js 20+, pnpm, Rust, and platform-specific system libraries.

Tolaria is a cross-platform desktop application for managing markdown notes, built with Tauri, React, and TypeScript. According to the refactoringhq/tolaria repository, the app stores notes as plain markdown files with Git versioning and can be installed either via prebuilt binaries or by compiling the source code locally.

Installing Tolaria from Prebuilt Binaries

The fastest way to install Tolaria is using the signed release binaries distributed through official channels.

macOS Installation via Homebrew

For macOS users, Tolaria is available as a Homebrew Cask. This method installs the signed and notarized application bundle automatically.

brew install --cask tolaria

This command corresponds to the installation instructions in [README.md](https://github.com/refactoringhq/tolaria/blob/main/README.md#L38-L42), lines 38-42. The cask downloads the latest stable release and places Tolaria in your Applications folder.

Windows and Linux Installation

For Windows and Linux users, or macOS users who prefer manual installation, download the appropriate asset from the releases page.

1. Visit the latest release page.
2. Download the .exe for Windows, .AppImage for Linux, or .dmg for macOS.
3. Run the installer or execute the binary directly.

The release assets are built as portable executables, requiring no additional installation steps. This distribution method is documented in [README.md](https://github.com/refactoringhq/tolaria/blob/main/README.md#L44-L47), lines 44-47.

Building Tolaria from Source

If you prefer to compile Tolaria yourself or want to run the latest development version, you must install the prerequisites and build the Tauri-based application locally.

Required Dependencies

Before cloning the repository, ensure your system meets the following requirements:

• Node.js 20 or higher
• pnpm 8 or higher (npm i -g pnpm)
• Rust stable toolchain (2021 edition)
• Linux system libraries (Linux only): WebKit2GTK 4.1, GTK 3, and related development headers

For Linux distributions, install the specific packages as documented in [README.md](https://github.com/refactoringhq/tolaria/blob/main/README.md#L63-L81), lines 63-81:

• Arch/Manjaro: sudo pacman -S --needed webkit2gtk-4.1 base-devel curl wget file openssl appmenu-gtk-module libappindicator-gtk3 librsvg
• Debian/Ubuntu 22.04+: sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev libsoup-3.0-dev patchelf
• Fedora 38+: sudo dnf install webkit2gtk4.1-devel openssl-devel curl wget file libappindicator-gtk3-devel librsvg2-devel

Compile and Launch Commands

Once dependencies are installed, clone the repository and run the build commands:

# Install npm dependencies

pnpm install

# Option A: Run the web UI in your browser (mock mode)

pnpm dev

# Opens http://localhost:5173 per vite.config.ts configuration

# Option B: Build and launch the native desktop app

pnpm tauri dev

The pnpm tauri dev command compiles the Rust backend in src-tauri/ and launches the native window, as specified in [README.md](https://github.com/refactoringhq/tolaria/blob/main/README.md#L88-L96), lines 88-96.

Understanding Tolaria's Architecture

Understanding the underlying architecture helps troubleshoot installation issues and explains why certain dependencies are required.

Files-First Design

Tolaria follows a files-first, Git-first, offline-first philosophy. According to [docs/ARCHITECTURE.md](https://github.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md#L7-L10), lines 7-10, the filesystem is the single source of truth. Notes are stored as plain .md files with optional YAML front-matter, and the UI never maintains its own copy—it reads and writes directly to disk via Tauri IPC calls.

Three-Layer Data Flow

The application implements a three-layer architecture documented in [docs/ARCHITECTURE.md](https://github.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md#L52-L58), lines 52-58:

1. Filesystem: Plain markdown files on disk
2. Cache: Located at ~/.laputa/cache/..., managed by src-tauri/src/vault/cache.rs
3. React State: VaultEntry[] arrays consumed by the UI

The cache rebuilds automatically when filesystem changes occur, ensuring consistency between the UI and disk.

MCP Server Component

Tolaria includes an MCP (Model-Context-Protocol) server bridge for AI integration. The Node.js server in mcp-server/index.js exposes vault operations via WebSocket ports 9710 (tool bridge) and 9711 (UI bridge), as detailed in [docs/ARCHITECTURE.md](https://github.com/refactoringhq/tolaria/blob/main/docs/ARCHITECTURE.md#L26-L31), lines 26-31.

Development and Debugging Workflows

When running from source, you may need to start specific components individually.

Launch the MCP Server Manually

To debug AI integrations or run the tool server separately:

cd mcp-server
node index.js

This starts the stdio and WebSocket bridge on ports 9710/9711. The entry point is defined in mcp-server/index.js, with Rust-side handling in src-tauri/src/mcp.rs.

Web Development Mode

For UI development without compiling the Rust backend:

pnpm dev

This starts the Vite dev server configured in vite.config.ts, running the React interface against mock data in your browser.

Summary

• Install via Homebrew on macOS using brew install --cask tolaria for automatic updates and signed binaries.
• Download binaries for Windows (.exe) and Linux (.AppImage) from the official releases page.
• Build from source requires Node.js 20+, pnpm, Rust, and Linux-specific GTK/WebKit libraries for Tauri compilation.
• Run the app using pnpm tauri dev for the native desktop experience or pnpm dev for browser-based development.
• Key files include src-tauri/src/vault/cache.rs for caching logic and mcp-server/index.js for AI tool integration.

Frequently Asked Questions

What are the minimum system requirements for Tolaria?

Tolaria requires macOS 10.13+, Windows 10/11, or Linux with GTK 3 and WebKit2GTK 4.1. For source builds, you need Node.js 20 or higher, pnpm 8+, and the Rust stable toolchain. The application runs offline and uses minimal resources, as it relies on the filesystem rather than a local database server.

Can I run Tolaria on Linux without installing system libraries?

No. Tauri applications require native system libraries for Web rendering. On Linux, you must install libwebkit2gtk-4.1-dev and related development headers before building. However, if you download the prebuilt .AppImage from the releases page, the libraries are bundled, and no system-wide installation is required.

How do I update Tolaria to the latest version?

If installed via Homebrew, run brew upgrade --cask tolaria. For binary installations, download the latest release from the GitHub releases page and replace the existing application. When building from source, pull the latest changes from the repository and rerun pnpm install && pnpm tauri dev.

Where does Tolaria store my notes and configuration data?

Tolaria stores notes as plain markdown files in a vault directory you specify at first launch. Application settings and the internal cache reside in platform-specific directories (typically ~/.laputa/ on Unix systems). Since Tolaria uses a files-first architecture, your notes remain accessible as standard .md files even if you uninstall the application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}