# How to Build OpenLogi from Source Code: Complete Rust Build Guide

> Learn to build OpenLogi from source code using Cargo. Follow our Rust build guide to compile openlogi-agent, openlogi-desktop, and openlogi-cli after installing system dependencies on Linux.

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

---

**Building OpenLogi from source code requires compiling three separate Rust crates—`openlogi-agent`, `openlogi-desktop`, and `openlogi-cli`—using Cargo after installing system dependencies like `libudev-dev` and `libwayland-dev` on Linux.**

OpenLogi is a native, local-first replacement for Logitech Options+ written in Rust. The project follows a multi-process architecture where the graphical interface, background device service, and optional overlay operate as distinct binaries communicating via IPC. This guide walks through the complete build process using the source files located in the `AprilNEA/OpenLogi` repository.

## Prerequisites for Building OpenLogi

Before compiling, you must install the Rust toolchain and platform-specific system libraries that enable USB HID communication and GPU-accelerated UI rendering.

### Install the Rust Toolchain

OpenLogi pins a specific Rust version in [`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml) using the 2024 edition. Install rustup and the required toolchain:

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

```

### Linux System Dependencies

The build requires development headers for udev, Wayland, X11, and font configuration. According to [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) at line 15, install these 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 support the **HID++ device protocol** handling in the agent and the **GPUI-based interface** rendering in the desktop application.

### macOS Packaging Tools (Optional)

For creating distributable bundles on macOS, install additional helpers referenced at lines 16-17 of [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md):

```bash
brew install create-dmg

```

This dependency is handled automatically when running the macOS bundle task through the `xtask` helper.

## Understanding the OpenLogi Architecture

The project splits functionality across three main processes defined in the workspace [`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml):

- **`openlogi-agent`** (`crates/openlogi-agent`): Background daemon that communicates directly with HID++ devices via USB
- **`openlogi-desktop`** (`crates/openlogi-desktop`): GUI client built on the GPUI framework that renders the user interface
- **`openlogi-overlay`** (`crates/openlogi-overlay`): Optional cursor-centered action ring for quick shortcuts

All three coordinate through **tarpc IPC contracts** defined in `crates/openlogi-ipc`, as documented in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) between lines 17-45. The `openlogi` CLI crate (`crates/openlogi-cli`) provides a thin wrapper for command-line interactions with the agent.

## Build Steps for OpenLogi

### Clone the Repository

Begin by cloning the source code and entering the workspace directory:

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

```

### Compile the Binaries

Build all three production binaries in release mode for optimal performance. The command pattern shown in [`docs/INSTALL-linux.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/INSTALL-linux.md) at line 70 specifies building multiple packages simultaneously:

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

```

This produces three executables in `target/release/`:
- `openlogi` (the CLI wrapper)
- `openlogi-desktop` (the GUI application)
- `openlogi-agent` (the background service)

### Run the Components

During development, you can run the agent and desktop separately in different terminals. The workflow documented at lines 134-135 of [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) demonstrates using a mock agent when hardware is unavailable:

```bash

# Terminal 1: Start the mock agent for development

cargo run -p openlogi-agent --bin openlogi-agent-mock

# Terminal 2: Launch the GUI connected to the existing mock

OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

```

Setting `OPENLOGI_DEV_AGENT=0` prevents the GUI from spawning a new agent process, allowing it to connect to your manually started mock or real agent instance.

## Development Workflow with Mock Devices

When building OpenLogi without physical Logitech hardware, use the **mock agent binary** (`openlogi-agent-mock`) to simulate device connections. This binary is defined in the same `openlogi-agent` crate but provides synthetic HID++ responses for UI testing.

Start the mock server:

```bash
cargo run -p openlogi-agent --bin openlogi-agent-mock

```

Then launch the desktop application with the development flag to bypass agent auto-spawn:

```bash
OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

```

This configuration allows you to iterate on UI changes in `crates/openlogi-desktop` without requiring USB device access.

## Packaging OpenLogi for Distribution

The repository includes an `xtask` automation crate ([`xtask/README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/README.md)) that handles code signing, resource bundling, and installer creation.

### macOS Bundle Creation

Generate a signed `.app` bundle suitable for macOS:

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

```

Create a distributable DMG:

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

```

### Linux Package Assembly

For Linux distributions, the xtask helper copies binaries and installs udev rules:

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

```

These packaging commands are fully documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) between lines 230-255 and handle platform-specific requirements like plist generation on macOS or udev rule installation on Linux.

## Summary

- **OpenLogi consists of three Rust crates**: `openlogi-agent` (background service), `openlogi-desktop` (GUI), and `openlogi-cli` (command wrapper) coordinated via tarpc IPC.
- **System dependencies are critical**: Linux builds require `libudev-dev`, `libwayland-dev`, and `libxkbcommon-x11-dev` for hardware access and windowing.
- **Build with Cargo**: Use `cargo build --release -p openlogi -p openlogi-desktop -p openlogi-agent` to compile all binaries.
- **Mock development**: Use `openlogi-agent-mock` and `OPENLOGI_DEV_AGENT=0` to develop without physical hardware.
- **Automated packaging**: The `xtask` crate provides `macos bundle`, `macos package`, and `linux package` commands for distribution.

## Frequently Asked Questions

### What version of Rust is required to build OpenLogi?

OpenLogi requires the stable Rust toolchain specified in [`rust-toolchain.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/rust-toolchain.toml), which uses the **2024 edition**. The rustup installer automatically manages this version when you run `cargo` commands in the repository root.

### Can I run OpenLogi without a physical Logitech device?

Yes. The codebase includes a **mock agent** binary (`openlogi-agent-mock`) that simulates HID++ device responses. Run the mock agent in one terminal, then start the desktop application with `OPENLOGI_DEV_AGENT=0` to connect to the simulated hardware instead of spawning a real agent.

### Where are the build commands documented in the source code?

The primary installation instructions reside in [`docs/INSTALL-linux.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/INSTALL-linux.md) at line 70, while the complete development workflow including packaging is documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) between lines 15-255. The [`xtask/README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/README.md) file contains specific details about the custom automation commands.

### How do the three OpenLogi processes communicate?

The **agent**, **desktop**, and **overlay** processes communicate via **tarpc** (a tar-based RPC framework) using contracts defined in `crates/openlogi-ipc`. This IPC architecture allows the GUI to run as an unprivileged user process while the agent handles raw USB HID++ communication with elevated permissions.