How to Build OpenLogi from Source: A Complete Rust Compilation Guide

Building OpenLogi requires installing the Rust toolchain, cloning the repository, and compiling multiple workspace crates including openlogi-agent, openlogi-desktop, and openlogi-cli using cargo build --release.

OpenLogi is a native, local-first alternative to Logitech Options+ written in Rust. Its architecture splits functionality across several independent crates that produce distinct binaries for the command-line interface, desktop GUI, and background device agent. Building OpenLogi from source means compiling these crates to create a fully functional local installation.

Prerequisites and Toolchain Setup

Before you can build OpenLogi, you must install the Rust compiler and platform-specific system libraries. The repository pins a specific toolchain via rust-toolchain.toml (stable Rust, edition 2024, MSRV 1.98).

Install Rust

Use rustup to install the pinned toolchain:

rustup update
rustup show

This reads the rust-toolchain.toml file in the repository root and installs the correct version automatically.

Linux System Dependencies

For device discovery and udev integration on Debian/Ubuntu systems, install the required development packages:

sudo apt-get install libudev-dev gcc g++ clang libfontconfig-dev \
    libwayland-dev libxkbcommon-x11-dev libx11-xcb-dev libssl-dev \
    libzstd-dev pkg-config

These libraries enable the openlogi-agent to communicate with Logitech hardware over HID++.

macOS Requirements

Building the GPUI-based desktop application on macOS requires Xcode 16 or newer with the Metal Toolchain component. For packaging, optionally install create-dmg via Homebrew and cargo-bundle.

Cloning the Repository

Clone the OpenLogi source code from GitHub:

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

This downloads all crates located in the crates/ directory, including the core agent logic in crates/openlogi-agent/src/agent.rs and the IPC definitions in crates/openlogi-ipc/src/ipc.rs.

Compiling the OpenLogi Binaries

OpenLogi uses a workspace structure where each binary resides in its own crate. The three primary production binaries are:

• openlogi (crates/openlogi): Thin CLI wrapper that delegates to openlogi-cli
• openlogi-desktop (crates/openlogi-desktop): GPUI-based desktop GUI client
• openlogi-agent (crates/openlogi-agent): Background service handling HID++ I/O and DPI cycles

Compile all three in release mode:

cargo build --release -p openlogi -p openlogi-desktop -p openlogi-agent

The resulting executables appear in target/release/:

• target/release/openlogi — Entry point defined in crates/openlogi/src/main.rs
• target/release/openlogi-desktop — GUI launcher defined in crates/openlogi-desktop/src/main.rs
• target/release/openlogi-agent — Agent daemon defined in crates/openlogi-agent/src/main.rs

To include the Actions Ring overlay, add -p openlogi-overlay to the build command.

Post-Build Installation and Setup

Installing Binaries

Copy the compiled binaries to a directory in your $PATH, or install the CLI directly via Cargo:

cargo install --path crates/openlogi

This installs only the openlogi wrapper and openlogi-cli components. The desktop application and agent typically remain in target/release/ and are launched directly.

Linux udev Rules

The openlogi-agent requires write access to /dev/uinput and read/write access to /dev/hidraw* devices. Install the bundled udev rules:

sudo cp packaging/linux/udev/70-openlogi.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

These rules grant the necessary permissions for the agent to communicate with Logitech peripherals without root privileges.

Running OpenLogi

Starting the Background Agent

First, verify uinput access:

./target/release/openlogi-agent --check-uinput

If installed as a systemd user service, enable and start it:

systemctl --user enable --now openlogi-agent.service

The agent listens for connections from the GUI via a local tarpc IPC socket defined in crates/openlogi-ipc/src/ipc.rs.

Launching the Desktop GUI

With the agent running, start the graphical interface:

./target/release/openlogi-desktop

The GPUI-based client automatically connects to the agent and displays device status, DPI settings, and button configurations.

Optional Packaging

For distribution, OpenLogi includes xtask commands that automate packaging.

macOS DMG Creation

cargo run -p xtask -- macos package

This command, implemented in xtask/src/commands/macos/dmg.rs, produces target/release/OpenLogi.dmg ready for distribution.

Linux Package Creation

cargo run -p xtask -- linux package

This creates .deb, .rpm, or .pkg.tar.zst files using nfpm, as defined in xtask/src/commands/linux.rs.

Summary

• OpenLogi consists of multiple Rust crates producing the openlogi CLI, openlogi-desktop GUI, and openlogi-agent background service.
• The build requires Rust 1.98+ (managed via rust-toolchain.toml) and platform-specific libraries like libudev-dev on Linux or Xcode on macOS.
• Compile production binaries using cargo build --release with -p flags for each crate.
• Linux systems require installing udev rules from packaging/linux/udev/70-openlogi.rules to grant device access permissions.
• The agent and GUI communicate via tarpc IPC using the protocol defined in crates/openlogi-ipc/src/ipc.rs.

Frequently Asked Questions

What crates make up the OpenLogi project?

The workspace contains several crates: openlogi (CLI wrapper), openlogi-cli (command tree implementation), openlogi-desktop (GPUI frontend), openlogi-agent (background HID++ handler), openlogi-overlay (Actions Ring helper), and openlogi-ipc (tarpc communication layer). The agent crate also includes a openlogi-agent-mock binary for development without physical hardware.

Do I need physical Logitech hardware to build OpenLogi?

No. You can compile all components without connected devices. For development and testing without hardware, build the mock agent binary using cargo build --release -p openlogi-agent and run it instead of the standard agent.

How do I enable the agent to access HID devices on Linux?

Copy the provided udev rule file from packaging/linux/udev/70-openlogi.rules to /etc/udev/rules.d/, then reload the rules with udevadm control --reload-rules. This grants the agent write access to /dev/uinput and read/write access to /dev/hidraw* nodes required for Logitech device communication.

Can I build just the CLI without the desktop GUI?

Yes. Omit the -p openlogi-desktop flag from the build command. The CLI components (openlogi and openlogi-cli) have fewer system dependencies and do not require the Metal Toolchain or fontconfig libraries needed for the GPUI-based desktop application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}