> ## Documentation Index
> Fetch the complete documentation index at: https://docs.luminy.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Luminy Installation Guide: macOS, Windows, and Linux

> Download and install Luminy on macOS, Windows, or Linux. Luminy updates automatically in the background when new versions are available.

Luminy is distributed as a native desktop application built with Tauri, which means you get a single, self-contained installer for your platform — no package managers, no runtimes, and no build steps required. This page covers how to download and install Luminy on any supported operating system and explains how the built-in auto-updater keeps your installation current.

## System requirements

Luminy is a lightweight native app and runs comfortably on any modern machine meeting the following requirements.

| Requirement          | Details                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Operating system** | macOS 11 (Big Sur) or later · Windows 10 or later · Major Linux distributions (Ubuntu 20.04+, Fedora 37+, Arch, etc.) |
| **Architecture**     | x86-64 or Apple Silicon (arm64)                                                                                       |
| **Disk space**       | \~80 MB for the app bundle; additional space for your project indexes and session database                            |
| **Node.js / Rust**   | **Not required** — the app is fully bundled. No developer toolchain needed for end users.                             |

<Note>
  If you want to use local AI models through Ollama, you will need [Ollama](https://ollama.com) installed separately and enough RAM to run your chosen model. Ollama itself is not bundled with Luminy.
</Note>

## Download

Visit **[luminy.tech](https://luminy.tech)** and click the download button for your platform. The site auto-detects your OS, but you can also scroll down to choose a specific platform or architecture manually.

The current release is **v1.5.4**.

## Installation

<Tabs>
  <Tab title="macOS">
    <Steps>
      <Step title="Open the disk image">
        Double-click the downloaded `.dmg` file to mount it. A Finder window will open showing the Luminy app icon alongside a shortcut to your Applications folder.
      </Step>

      <Step title="Drag to Applications">
        Drag **Luminy.app** into the **Applications** folder shortcut. Wait for the copy to finish.
      </Step>

      <Step title="Launch Luminy">
        Open **Launchpad** or navigate to `/Applications` in Finder and double-click **Luminy** to launch it.
      </Step>

      <Step title="Allow the app to run (first launch only)">
        On the very first launch, macOS Gatekeeper may show a warning because the app was downloaded from the internet. Click **Open** in the dialog to proceed. You will not see this prompt again.
      </Step>
    </Steps>

    <Warning>
      If macOS says it "cannot be opened because the developer cannot be verified" and does not show an **Open** button, right-click (or Control-click) **Luminy.app** in Finder and choose **Open** from the context menu. This bypasses Gatekeeper for that first launch only.
    </Warning>
  </Tab>

  <Tab title="Windows">
    <Steps>
      <Step title="Run the installer">
        Double-click the downloaded `.msi` or `.exe` installer. If Windows SmartScreen shows a warning, click **More info → Run anyway** to proceed.
      </Step>

      <Step title="Follow the setup wizard">
        Accept the license agreement and choose an install location (the default is `%LOCALAPPDATA%\Luminy`). Click **Install** and wait for the wizard to finish.
      </Step>

      <Step title="Launch Luminy">
        The installer creates a desktop shortcut and a Start Menu entry. Double-click either to open Luminy.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Linux">
    <Steps>
      <Step title="Choose your package format">
        Luminy is available as an **AppImage** (runs on any distro without installation), a **`.deb`** package (Debian/Ubuntu), and an **`.rpm`** package (Fedora/RHEL). Download the format that matches your system.
      </Step>

      <Step title="Install or make executable">
        <CodeGroup>
          ```bash AppImage theme={null}
          chmod +x Luminy_1.5.4_amd64.AppImage
          ./Luminy_1.5.4_amd64.AppImage
          ```

          ```bash Debian / Ubuntu (.deb) theme={null}
          sudo dpkg -i luminy_1.5.4_amd64.deb
          ```

          ```bash Fedora / RHEL (.rpm) theme={null}
          sudo rpm -i luminy_1.5.4_x86_64.rpm
          ```
        </CodeGroup>
      </Step>

      <Step title="Launch Luminy">
        For AppImage, run the file directly (or integrate it with [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher)). For `.deb` and `.rpm` installs, Luminy will appear in your application menu or you can launch it from a terminal by running `luminy`.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Automatic updates

Luminy includes a built-in auto-updater powered by signed release artifacts hosted at `https://luminy.tech/api/updates`. Here is how it works.

* **Background checks** — When Luminy is running, it periodically polls the update endpoint for new releases.
* **Silent download** — If a new version is available, Luminy downloads the update in the background without interrupting your work.
* **Prompt to restart** — Once the download is complete, Luminy shows an unobtrusive notification asking whether you want to restart and apply the update now or wait until the next time you open the app.
* **No manual action needed** — You never need to visit the download page again after the initial install.

All update artifacts are cryptographically signed. Luminy verifies the signature before applying any update, so you are protected against tampering.

<Note>
  Auto-updates are supported on macOS and Windows out of the box. On Linux, auto-updates are available for AppImage installs. If you installed via `.deb` or `.rpm`, update through your system package manager or re-download from [luminy.tech](https://luminy.tech) when a new version is released.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="macOS: 'Luminy cannot be opened because the developer cannot be verified'">
    This is macOS Gatekeeper blocking an app that hasn't been opened before. Right-click (or Control-click) **Luminy.app** in Finder, choose **Open** from the context menu, then click **Open** in the dialog that appears. You only need to do this once — future launches will open normally.
  </Accordion>

  <Accordion title="Windows: SmartScreen warning on first launch">
    Windows SmartScreen may flag newly published executables. Click **More info** and then **Run anyway** to proceed. This prompt disappears once the app has been run enough times to build a reputation with Microsoft's system.
  </Accordion>

  <Accordion title="Linux: AppImage doesn't launch">
    Make sure the file has executable permissions (`chmod +x Luminy_*.AppImage`). On some distributions you may also need to install `libfuse2` — for example, on Ubuntu 22.04+: `sudo apt install libfuse2`.
  </Accordion>

  <Accordion title="The app opens but is blank or crashes immediately">
    Try deleting the app's local data directory and relaunching. On macOS this is `~/Library/Application Support/Luminy`; on Windows it is `%APPDATA%\Luminy`; on Linux it is `~/.config/Luminy`. This resets Luminy to a clean state without uninstalling it.
  </Accordion>
</AccordionGroup>