Installation

Loach ships as a native desktop app for Windows, Linux and macOS. Install from a pre-built package, or build from source.

Windows Linux macOS MIT licensed

System requirements

Loach itself is light. What your machine needs depends on the local models you run - Ollama’s own GPU and memory requirements apply. Remote OpenAI-compatible endpoints need nothing extra.

Install from a pre-built package

With every stable release the project publishes ready-to-install packages for each supported operating system. Head over to the GitHub releases page and download the file that matches your platform.

Download the latest release →

The first time you open Loach, the setup wizard walks you through choosing a provider, pulling a model and picking your defaults.

Loach runs as a single instance. Launching it again - from the Start menu, a desktop file or the app icon - brings the running window forward, out of the tray too, instead of starting a second copy.

Windows

1. Download the .exe from the latest release.
2. Run the installer and follow the prompts. It installs for your user account, so it doesn’t need administrator rights.
3. Launch Loach from the Start menu.

WebView2 is required and is pre-installed on Windows 11. On Windows 10 the installer will pull it in if it's missing.

Linux

From the folder you downloaded the package to, pick the format for your distribution:

# Debian / Ubuntu
sudo apt install ./Loach_*_amd64.deb

# Fedora / RHEL
sudo dnf install ./Loach-*.x86_64.rpm

# openSUSE
sudo zypper install ./Loach-*.x86_64.rpm

# Any distro
chmod +x Loach_*_amd64.AppImage
./Loach_*_amd64.AppImage

Builds target glibc 2.35, which makes Ubuntu 22.04 and Debian 12 the oldest supported distributions. All three formats - .AppImage, .deb and .rpm - support in-app updates; package installs download the signed package and elevate through pkexec so the package database stays consistent. There is no apt or yum repository, so apt upgrade won't see new versions.

Saving an API key or an app lock uses your desktop’s Secret Service (GNOME Keyring or KWallet). Minimal setups without one can’t store secrets - see Key won’t save on Linux.

macOS

1. Download the .dmg from the latest release.
2. Open it and drag Loach into Applications.
3. On first launch macOS will block the app with a “Loach is damaged and can’t be opened” or “Apple cannot verify…” warning, because the build is not Apple-notarized. Bypass it once and the app runs normally (see below).

• For “Apple cannot verify…” on macOS 14 and earlier: right-click Loach.app in Applications → Open → click Open in the prompt.
• For “Apple cannot verify…” on macOS 15 and later: try to open the app once, then click Open Anyway in System Settings → Privacy & Security.
• For either warning: run the command below in Terminal, then launch the app normally.

xattr -cr /Applications/Loach.app

Auto-updates are delivered through Loach’s own signed updater (independent of Apple), so you only need to do this once on install. If a future update is blocked the same way, the same workaround applies.

Only Apple Silicon (M-series) Macs running macOS 11 or later are supported, and they need Safari 16.4 or later. Loach’s window runs on the system’s WebKit, which follows the installed Safari rather than the macOS version, so a Big Sur or Monterey Mac still on Safari 14 or 15 has to update Safari first. Intel Macs are not supported.

Like other Mac apps, Loach stays running when you close its window (the red button or ⌘ + W): click its Dock icon to bring it back, and quit with ⌘ + Q or Quit in its menu-bar icon. With an app lock set, closing the window also locks it.

Build from source

If you want the bleeding edge or you're contributing patches, build from the repository.

Prerequisites

• Node.js 22.13+ (or 24 / 26+) and npm - the locked pdfjs-dist 6 needs 22.13, and Vitest 5 runs only on Node 22, 24 and 26+.
• Rust 1.90+ via rustup - the dependency tree's minimum; CI builds on 1.90.0.
• Platform build tooling - see the official Tauri prerequisites guide.
  • Windows: Microsoft Visual Studio Build Tools, WebView2 runtime (pre-installed on Windows 11).
  • Linux: libwebkit2gtk-4.1-dev, libappindicator3-dev (or libayatana-appindicator3-dev), librsvg2-dev, build-essential, libssl-dev, pkg-config. Bundling the .AppImage and .rpm also needs patchelf, rpm, file, wget and desktop-file-utils. No Secret Service headers are needed - the keyring backend is pure Rust.
  • macOS: Xcode Command Line Tools (xcode-select --install).

Clone and install

git clone https://github.com/ztcs-software/loach.git
cd loach
npm install

Run in development

npm run tauri dev

The Vite dev server runs on http://localhost:1420 and the Tauri shell embeds it.

Build production installers

npm run tauri -- build --no-sign

--no-sign skips the signed updater artifacts, which need the release signing key (TAURI_SIGNING_PRIVATE_KEY). Without the flag and the key, the build fails after bundling. Outputs land in src-tauri/target/release/bundle/:

• Windows: .exe (NSIS)
• Linux: .deb, .rpm and .AppImage
• macOS: .dmg and .app

Linux build in Docker

The repository’s Dockerfile builds the Linux .deb and .AppImage on Ubuntu 22.04 with the same Node.js and Rust versions CI uses, so the result runs on the oldest supported distributions. It only builds Loach; install the output on a Linux host.

docker build -t loach-build .
docker run --rm -v "$PWD/dist-linux:/out" loach-build

The packages land in dist-linux/deb/ and dist-linux/appimage/. They are unsigned, like any --no-sign build.

Updates

We regularly update Loach to deliver new features, bug fixes, security improvements, and performance gains. Every install format updates from inside the app: check manually in Settings → Updates, or switch on the opt-in auto-check and Loach tells you once per launch when a new version is out. Nothing downloads until you choose Update now. See OTA updates for details.