How to Use the OpenLogi Agent Mock for Development Without Hardware

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, 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 with the path src/bin/mock_agent.rs.

Execute the following command in your terminal:

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, 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:

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, 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:

OPENLOGI_PROFILE=dev cargo run -p openlogi-agent --bin openlogi-agent-mock

Refer to 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 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 specifically for development workflows.

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