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

> Learn how to install Tolaria on macOS, Windows, and Linux. Follow our complete setup guide for easy installation using brew, binaries, or compiling from source.

- Repository: [Refactoring/tolaria](https://github.com/refactoringhq/tolaria)
- Tags: getting-started
- Published: 2026-05-04

---

**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.

```bash
brew install --cask tolaria

```

This command corresponds to the installation instructions in [[`README.md`](https://github.com/refactoringhq/tolaria/blob/main/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](https://github.com/refactoringhq/tolaria/releases/latest) 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)](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)](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:

```bash

# 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)](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)](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)](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`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/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)](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:

```bash
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`](https://github.com/refactoringhq/tolaria/blob/main/mcp-server/index.js), with Rust-side handling in [`src-tauri/src/mcp.rs`](https://github.com/refactoringhq/tolaria/blob/main/src-tauri/src/mcp.rs).

### Web Development Mode

For UI development without compiling the Rust backend:

```bash
pnpm dev

```

This starts the Vite dev server configured in [`vite.config.ts`](https://github.com/refactoringhq/tolaria/blob/main/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`](https://github.com/refactoringhq/tolaria/blob/main/src-tauri/src/vault/cache.rs) for caching logic and [`mcp-server/index.js`](https://github.com/refactoringhq/tolaria/blob/main/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.