Lutra/docs/install.md
danny bd225d9e3a B1: alpha installers (NSIS, DMG), identifier com.tyrveil.lutra with data migration
- App identifier com.tyrveil.lutra (D26) in tauri.conf.json and
  rendezvous::APP_IDENTIFIER; a test keeps them equal.
- First normal start copies settings.json, recovery/ and tools/ once from
  the dev.lutra.desktop directories (staging dir + rename, logged, info
  notification); old directories stay untouched.
- Bundling on: per-user NSIS setup (English, German, Start menu, optional
  desktop shortcut, uninstaller) and DMG; `cargo xtask bundle` builds the
  platform's installer, joining the DMG backgrounds into a HiDPI TIFF on
  macOS. build.rs also writes icons/512x512.png for the .icns.
- Installer images from the banner, designed by Amy, generated by
  `cargo xtask installer-images` (assets/installer/, ASSETS.md rows);
  approved by Daniel.
- docs/install.md (SmartScreen, Gatekeeper, uninstall, data locations),
  README install section, architecture, development and macOS notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 21:48:15 +01:00

4.6 KiB

Installing Lutra

Status: draft, alpha installers · Last updated: 2026-10-31

Lutra's alpha comes as an installer for Windows (a setup .exe) and macOS (a .dmg). Both are not signed yet, so Windows and macOS warn before the first start; the steps below get past that once. Linux has no installer yet: build it from source (development.md).

The installers contain the desktop app only. The lutra command-line tool (lutra ., lutra mcp) is not in them yet; build it with cargo build --release -p lutra-cli if you need it.

Building an installer

On the platform you want the installer for:

cargo xtask bundle

It builds the release app with the bundled UI and prints the installer's path and size: target/release/bundle/nsis/Lutra_<version>_x64-setup.exe on Windows, target/release/bundle/dmg/Lutra_<version>_aarch64.dmg on macOS. It needs the Tauri CLI (cargo install tauri-cli --locked) and, on macOS, the Xcode Command Line Tools (macos.md).

Windows

Lutra installs for your user only: no administrator rights, no UAC prompt. It needs Microsoft Edge WebView2, which Windows 10 and 11 already have; if it is missing, the setup downloads it.

  1. Start Lutra_<version>_x64-setup.exe.
  2. Windows SmartScreen says "Windows protected your PC", because the setup is not signed. Click More info, check that the app is Lutra_<version>_x64-setup.exe and the publisher is "Unknown publisher", then click Run anyway. If you downloaded the file with a browser, the browser may ask first whether to keep it.
  3. The setup runs in English or German, following Windows. Click Next, keep or change the folder (default %LOCALAPPDATA%\Lutra), click Install.
  4. On the last page, tick Create desktop shortcut if you want one, and click Finish.

Lutra is now in the Start menu as Lutra. Installing a newer setup over it updates it in place and keeps your settings.

For scripts: Lutra_<version>_x64-setup.exe /S installs silently with both shortcuts, /D=C:\path (last argument) picks the folder, /NS skips the shortcuts.

Uninstalling on Windows

Settings → Apps → Installed apps → Lutra → … → Uninstall, or run uninstall.exe in the install folder. The uninstaller removes the app and its shortcuts. Your settings, recovery journal and Phpactor stay unless you tick Delete the application data.

macOS

The DMG holds the app for Apple Silicon (M1 or newer), macOS 11 or newer.

  1. Open Lutra_<version>_aarch64.dmg and drag Lutra onto Applications. Eject the DMG.
  2. The first start is blocked because the app is not signed or notarised. In Applications, right-click (or Control-click) Lutra → Open, and click Open in the dialog. On macOS 15 Sequoia and newer that dialog has no Open button: click Done, then open System Settings → Privacy & Security, scroll to "Lutra was blocked", click Open Anyway and confirm with your password.
  3. Alternatively, remove the quarantine flag once in Terminal and start Lutra normally:
xattr -dr com.apple.quarantine /Applications/Lutra.app

You need to do this once per installed version.

Uninstalling on macOS

Quit Lutra and drag Lutra from Applications to the Trash. Your data stays; delete the folders below to remove it.

Where your data lives

What Windows macOS
The app %LOCALAPPDATA%\Lutra\ /Applications/Lutra.app
Settings (settings.json), recovery journal (recovery\), downloaded Phpactor (tools\) %APPDATA%\com.tyrveil.lutra\ ~/Library/Application Support/com.tyrveil.lutra/
Window data of the web view (recent projects, layout) %LOCALAPPDATA%\com.tyrveil.lutra\ ~/Library/WebKit/com.tyrveil.lutra/, ~/Library/Caches/com.tyrveil.lutra/

On Linux, when built from source: settings in ~/.config/com.tyrveil.lutra/, journal and tools in ~/.local/share/com.tyrveil.lutra/.

From a build before the installers. Earlier builds used the identifier dev.lutra.desktop. The first start of a new build copies settings.json, the recovery journal and the downloaded Phpactor from the old dev.lutra.desktop folders once and shows a notification; the old folders stay untouched and can be deleted afterwards. Recent projects and the window layout are not copied.

An instance started with --control PORT or --data-dir DIR keeps its files in its own folder (see development.md).

Revision history

Date Change Summary
2026-10-31 major B1: initial version, NSIS setup and DMG, unsigned