# How to Run the OpenLogi Desktop GUI in Development Mode

> Learn to run the OpenLogi desktop GUI in development mode. Use simple cargo commands or create a macOS dev bundle for an enhanced experience.

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

---

**Launch the OpenLogi desktop GUI in development mode by running `cargo run -p openlogi-desktop` from the workspace root, or use `cargo run -p xtask -- macos dev-bundle` on macOS to generate a proper `.app` bundle with the correct icon and menu-bar name.**

The OpenLogi project provides a Rust-based desktop GUI for managing Logitech devices. Whether you are contributing to the codebase or testing features locally, this guide covers the exact commands and configuration files needed to run the `openlogi-desktop` binary in development mode according to the AprilNEA/OpenLogi source code.

## Quick Start with Cargo

The simplest way to run the GUI uses Cargo's workspace-aware package selection. The binary entry point resides in [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs).

### Basic Launch

Execute the following from the repository root to build and run the GUI in debug mode:

```bash
cargo run -p openlogi-desktop

```

This compiles the raw binary (not a macOS `.app` bundle), which is sufficient for rapid iteration across Linux and macOS.

### macOS Development Bundle

For macOS developers who need the proper app icon and menu-bar label **OpenLogi Dev**, the workspace provides an `xtask` runner defined in [`.cargo/config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/.cargo/config.toml):

```bash
cargo run -p xtask -- macos dev-bundle
open target/dev/OpenLogi.app

```

The first command invokes the bundling logic implemented in [`xtask/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/main.rs), which assembles `target/dev/OpenLogi.app` as documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) (lines 81-90). The second command launches the bundled application with full macOS integration.

## Hardware-Free Development with Mock Agent

You can develop and test the GUI without physical Logitech hardware by using the mock IPC server implemented in [`crates/openlogi-agent/src/bin/openlogi-agent-mock.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/openlogi-agent-mock.rs).

### Starting the Mock IPC Server

Start the mock agent in the background before launching the GUI:

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

```

### Connecting the GUI to the Mock Agent

Prevent the GUI from auto-spawning its own agent by setting `OPENLOGI_DEV_AGENT=0`, then launch the desktop client:

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

```

This configuration binds the GUI to the mock server, satisfying the IPC contract without requiring USB hardware. These commands are documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) (lines 23-31).

## Optional Nix-Based Development Environment

If you use the optional `devenv` Nix shell, the repository exposes preconfigured tasks that mirror the Cargo workflows. Run the GUI with:

```bash
devenv tasks run openlogi:gui

```

For comprehensive checks including formatting, Clippy, tests, and documentation, execute:

```bash
devenv tasks run openlogi:check

```

These tasks are documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) (lines 44-51), which serves as the primary reference for the project's development workflow.

## Summary

- **Use `cargo run -p openlogi-desktop`** for the fastest cross-platform launch during development.
- **Generate macOS bundles** with `cargo run -p xtask -- macos dev-bundle` to test native app behavior including icons and menu-bar names.
- **Test without hardware** by running `openlogi-agent-mock` and setting `OPENLOGI_DEV_AGENT=0` before launching the GUI.
- **Reference [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md)** for authoritative command documentation and additional context on lines 23-31 (mock agent) and 81-90 (macOS bundling).

## Frequently Asked Questions

### What is the entry point for the OpenLogi desktop GUI?

The binary entry point is [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs). This file initializes the application and is executed when you run `cargo run -p openlogi-desktop`.

### How do I get the proper macOS app icon and menu bar name?

Run `cargo run -p xtask -- macos dev-bundle` to create `target/dev/OpenLogi.app`, then launch it with `open target/dev/OpenLogi.app`. This bundle displays the correct icon and shows **OpenLogi Dev** in the menu bar, unlike the raw binary.

### Can I test the GUI without Logitech hardware connected?

Yes. Start the mock IPC server with `cargo run -p openlogi-agent --bin openlogi-agent-mock`, then launch the GUI with `OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop`. This setup is documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) (lines 23-31) and uses the mock agent implementation in [`crates/openlogi-agent/src/bin/openlogi-agent-mock.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/openlogi-agent-mock.rs).

### Where are the development commands documented?

All development workflows, including Cargo commands and `devenv` tasks, are documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) at the repository root (specifically lines 44-51 for general tasks and lines 81-90 for macOS bundling).