# How to Install OpenLogi on Linux: Build from Source Guide

> Install OpenLogi on Linux by building from source. This guide walks you through compiling the Rust crate workspace for GUI, Agent, and Overlay components.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-09-08

---

**OpenLogi is primarily distributed for macOS via DMG and Homebrew, but Linux installation requires manually building the Rust crate workspace containing the GUI, Agent, and Overlay components.**

OpenLogi is a native, local-first replacement for Logitech Options+. While the project provides pre-built binaries and Homebrew casks for macOS users, the underlying Rust codebase supports Linux through manual compilation. According to the AprilNEA/OpenLogi repository structure, the application consists of three tightly-coupled Rust crates that must be built together to install OpenLogi on Linux.

## Understanding the Component Architecture

Before building, understand the three processes that comprise OpenLogi:

- **OpenLogi GUI** – The main application that presents the configuration UI and the Actions Ring overlay. Implementation resides in [`crates/openlogi-desktop/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/lib.rs).
- **OpenLogi Agent** – A background service that owns the HID++ device, handles DPI changes, SmartShift, and button events. Entry point is at [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs).
- **OpenLogi Overlay** – A thin client that draws the cursor-centered Actions Ring when invoked, implemented in [`crates/openlogi-overlay/src/platform.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/platform.rs).

These components communicate via a local-socket IPC layer, as demonstrated by the `openlogi_ipc` crate contract.

## Prerequisites for Linux Installation

To install OpenLogi on Linux, you need the Rust toolchain and system dependencies for HID access:

```bash

# Install Rust via rustup

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install Linux HID development libraries (Ubuntu/Debian example)

sudo apt-get install libhidapi-dev libudev-dev libusb-1.0-0-dev

```

## Building OpenLogi from Source

Since Linux lacks the DMG and Homebrew distribution channels available for macOS, compile the workspace directly:

```bash

# Clone the repository

git clone https://github.com/AprilNEA/OpenLogi.git
cd OpenLogi

# Build the complete workspace

cargo build --release

# The binaries will be available in:

# ./target/release/openlogi-agent

# ./target/release/openlogi-desktop (GUI)

```

## Post-Build Configuration

Unlike macOS, which uses [`crates/openlogi-permissions/src/macos.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-permissions/src/macos.rs) to request Input Monitoring, Camera, and Microphone permissions via native dialogs, Linux requires manual udev rules for HID++ device access:

```bash

# Create udev rule for Logitech HID++ devices

echo 'SUBSYSTEM=="hidraw", ATTRS{idVendor}=="046d", MODE="0666", GROUP="plugdev"' | \
  sudo tee /etc/udev/rules.d/99-logitech.rules
sudo udevadm control --reload-rules

```

## macOS Installation Reference

While installing OpenLogi on Linux requires building from source, the macOS installation process documented in [`README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/README.md) illustrates what the compiled components provide:

**Method 1: Download the notarized DMG**
- Download `OpenLogi.dmg` from the latest release
- Drag `OpenLogi.app` into `/Applications`

**Method 2: Install via Homebrew**

```bash
brew install --cask openlogi

```

To track upstream releases directly:

```bash
brew tap aprilnea/tap
brew install --cask aprilnea/tap/openlogi@latest

```

## Verifying Agent Communication

After building and launching both the agent and GUI, verify the IPC connection works:

```rust
// Example: checking agent status from Rust (uses the IPC contract)
use openlogi_ipc::client::OpenLogiClient;
let mut client = OpenLogiClient::connect().await?;
let status = client.get_status().await?;
println!("Agent running: {}", status.running);

```

## Summary

- OpenLogi uses a **three-process architecture** (GUI, Agent, Overlay) implemented in Rust crates
- Linux installation requires **building from source** using `cargo build --release` since pre-built binaries target macOS (DMG/Homebrew)
- Key source locations include [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs) for the background service and [`crates/openlogi-desktop/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/lib.rs) for the GUI
- Linux users must configure **udev rules** manually, unlike macOS which uses [`crates/openlogi-permissions/src/macos.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-permissions/src/macos.rs) for entitlement requests
- The IPC layer in `openlogi_ipc` enables communication between components once built

## Frequently Asked Questions

### Does OpenLogi provide pre-built binaries for Linux?

No. According to the repository source, official distribution channels currently provide notarized DMG files and Homebrew casks for macOS only. Linux users must compile the Rust workspace manually, targeting the crates in `crates/openlogi-*`.

### What system permissions does OpenLogi require on Linux?

OpenLogi requires access to HID raw devices (`/dev/hidraw*`) to communicate with Logitech peripherals via the HID++ protocol. Unlike macOS, which prompts for Input Monitoring, Camera, and Microphone through the implementation in [`crates/openlogi-permissions/src/macos.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-permissions/src/macos.rs), Linux requires manual udev rule configuration to grant the agent process device access.

### Can I run the OpenLogi Agent without the GUI on Linux?

Yes. The architecture separates concerns between the Agent (device handling) and GUI (configuration interface). You can run `cargo build --release -p openlogi-agent` to build only the background service, which manages DPI changes, SmartShift, and button events independently of the desktop interface.