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

> Learn how to build OpenLogi from source with this complete Rust compilation guide. Follow steps to install Rust, clone the repo, and compile workspace crates for your project.

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

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml) (stable Rust, edition 2024, MSRV 1.98).

### Install Rust

Use `rustup` to install the pinned toolchain:

```bash
rustup update
rustup show

```

This reads the [`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```bash
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:

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/agent.rs) and the IPC definitions in [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi/src/main.rs)
- `target/release/openlogi-desktop` — GUI launcher defined in [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs)
- `target/release/openlogi-agent` — Agent daemon defined in [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```bash
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:

```bash
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:

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

```

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

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs).

### Launching the Desktop GUI

With the agent running, start the graphical interface:

```bash
./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

```bash
cargo run -p xtask -- macos package

```

This command, implemented in [`xtask/src/commands/macos/dmg.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/commands/macos/dmg.rs), produces `target/release/OpenLogi.dmg` ready for distribution.

### Linux Package Creation

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.