# How to Use the OpenLogi Agent Mock for Development Without Hardware > Develop and test the OpenLogi GUI without hardware using the OpenLogi agent mock. This mock agent replicates the real agent's IPC contract for seamless development. - Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi) - Tags: how-to-guide - Published: 2026-08-21 --- **OpenLogi provides a hardware-free mock agent that implements the same IPC contract as the real agent, allowing you to develop and test the GUI without connecting physical Logitech HID++ devices.** The `AprilNEA/OpenLogi` repository includes a software-only mock implementation for developers who need to work on the desktop interface without access to Logitech HID++ hardware. This mock agent runs entirely in software while exposing the identical inter-process communication (IPC) surface used by the physical device agent. Understanding how to use the OpenLogi agent mock for development without hardware streamlines your workflow when hardware is unavailable or when you need predictable device states for UI testing. ## What Is the OpenLogi Agent Mock? The mock agent is a separate binary (`openlogi-agent-mock`) within the `openlogi-agent` crate that simulates the behavior of the real hardware agent. According to the source in [`crates/openlogi-agent/src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/mock_agent.rs), this implementation serves a **scripted inventory** over the agent IPC socket, presenting virtual devices with predefined capabilities to connected clients. Key characteristics of the mock include: - It uses the **`openlogi-dev`** profile by default, equivalent to setting `OPENLOGI_PROFILE=dev`. - It appends a **`-mock`** suffix to its version string (e.g., `0.9.0-mock`), making it visible in the UI that a mock session is active. - It competes for the same **single-instance lock** as the real agent, requiring careful startup sequencing to avoid conflicts. ## Starting the Mock Agent To launch the hardware-free mock, run the dedicated binary from the `openlogi-agent` crate. This binary is declared in [`crates/openlogi-agent/Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/Cargo.toml) with the path [`src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/bin/mock_agent.rs). Execute the following command in your terminal: ```bash cargo run -p openlogi-agent --bin openlogi-agent-mock ``` This starts the mock service listening on the IPC socket, ready to accept connections from the GUI or other clients. The mock requires no elevated privileges and does not attempt to access USB HID devices. ### Avoiding Conflicts with the Real Agent Because the mock competes for the same single-instance lock as the production agent, you must start the mock **before** the real agent, or ensure the real agent is not running. Running both simultaneously causes lock contention. As documented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md), isolate your mock sessions to prevent the production agent from claiming the IPC socket first. ## Connecting the GUI to the Mock Once the mock agent is running, any OpenLogi client automatically connects to the mock's IPC socket instead of searching for physical hardware. In a second terminal, launch the desktop GUI: ```bash cargo run -p openlogi-desktop ``` The GUI discovers the mock's scripted inventory and displays virtual devices with their capabilities. You can navigate settings, test configuration flows, and validate UI behavior without any Logitech hardware connected. ### Verifying Mock Connection Check the UI's agent version indicator to confirm you are running against the mock. The version string displayed will contain the **`-mock`** suffix, distinguishing it from production agent sessions. ## Limitations and Hardware-Only Features While the mock implements the full IPC surface required by the UI, it intentionally excludes functionality that requires physical hardware interaction. According to the implementation in [`mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/mock_agent.rs), the following actions are not supported: - **SmartShift torque adjustments** - **Actions Ring hardware interactions** These limitations are acceptable for GUI development because the mock preserves the complete IPC contract for device discovery, capability reporting, and configuration management. ## Configuration and Custom Profiles Although the mock defaults to the `openlogi-dev` profile, you can override environment variables to test different configurations. Set the profile explicitly when launching: ```bash OPENLOGI_PROFILE=dev cargo run -p openlogi-agent --bin openlogi-agent-mock ``` Refer to [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) for additional environment variables that customize the mock's behavior, including logging levels and IPC socket paths. ## Summary - The `openlogi-agent-mock` binary in [`crates/openlogi-agent/src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/mock_agent.rs) provides a complete software simulation of the hardware agent. - Start the mock with `cargo run -p openlogi-agent --bin openlogi-agent-mock` before launching the GUI to avoid single-instance lock conflicts. - The mock serves a scripted device inventory over IPC and appends `-mock` to its version string for easy identification. - Hardware-specific features like SmartShift torque are stubbed out, but all UI-relevant IPC endpoints remain functional. - Use this tool strictly for development and testing; it never accesses physical devices and is excluded from production builds. ## Frequently Asked Questions ### How do I know if the GUI is connected to the mock agent or the real agent? The GUI displays the agent version string in its interface. If the version ends with **`-mock`** (for example, `0.9.0-mock`), you are connected to the mock agent. The real agent displays a clean version number without this suffix. ### Can I run the mock agent and the real agent at the same time? No. Both agents compete for the same single-instance lock on the IPC socket. You must stop the real agent before starting the mock, or start the mock first to claim the lock. Attempting to run both simultaneously results in the second process failing to acquire the lock. ### Does the mock agent support all device features? No. The mock implements the IPC contract for device discovery and configuration, but it does not implement hardware-dependent actions such as **SmartShift torque adjustments** or **Actions Ring** interactions. It is designed for GUI development, not for testing hardware-specific logic. ### Is the mock agent included in production releases? No. The `openlogi-agent-mock` binary is strictly a development tool. It is never shipped in production builds and should not be used in environments where real hardware control is required. It is defined as a separate binary target in [`crates/openlogi-agent/Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/Cargo.toml) specifically for development workflows.