# OpenLogi Development Workflow: Dev Agent, Mock Inventory, and Hot‑Reloading Explained

> Discover OpenLogi's development workflow. Learn how the dev agent, mock inventory, and hot-reloading enable fast, hardware-free GUI development.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: internals
- Published: 2026-09-02

---

**OpenLogi's development workflow combines a dev app bundle, mock agent with scripted hardware inventory, and automatic hot‑reloading to enable hardware‑free, fast‑iteration GUI development.**

The AprilNEA/OpenLogi repository provides a sophisticated development environment for building Logitech device management software without requiring physical hardware. At the core of this system are three tightly coupled components: a temporary dev bundle, a mock agent that simulates complete device inventories, and a file‑watching hot‑reload mechanism that instantly reflects code changes in the running GUI.

## The Dev App Bundle

When you launch OpenLogi via Cargo, the desktop runner creates a temporary platform‑specific application bundle using the `openlogi-dev` profile. As implemented in [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md), this bundle performs automatic lifecycle management:

- Stops any previously started dev agent and overlay processes
- Starts fresh instances before the GUI launches
- Ensures the UI connects instantly to the correct IPC socket

This eliminates manual coordination between the desktop frontend and the agent backend. The dev bundle is the foundation that makes the rest of the workflow seamless.

## The Mock Agent (`openlogi-agent-mock`)

The **mock agent** is a hardware‑free binary located at [`crates/openlogi-agent/src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/mock_agent.rs) that implements the same tarpc `Agent` service interface as the production agent. It serves a **scripted, deterministic inventory** covering the full range of Logitech device types:

| Simulated Device | Behavior |
|-----------------|----------|
| Bolt receiver | USB receiver for wireless peripherals |
| Online mouse | Connected and responsive |
| Offline mouse | Disconnected state handling |
| Lighting‑capable keyboard | RGB/backlight control |
| Standalone Litra light | Elgato‑style camera lighting |
| Rotating foreground apps | Simulates `camera_active` flag flipping every 30 seconds |

Because the mock defaults to the **dev profile**, it communicates over the dev socket without interfering with any production OpenLogi installation. Writes to DPI, SmartShift, and lighting settings persist in memory, enabling realistic testing of configuration flows.

### Environment Variables for Mock Control

```bash

# Use production socket (test against real production GUI)

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

# Allow coexistence with an already‑running real agent

OPENLOGI_ALLOW_EXTERNAL_AGENT=1 cargo run -p openlogi-agent --bin openlogi-agent-mock

```

## Hot‑Reloading and Watch‑Based Restarts

The dev runner implements **automatic process lifecycle management** based on file watching. According to [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) and [`crates/openlogi-agent-core/src/watchers/poll.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent-core/src/watchers/poll.rs):

1. The runner watches the built agent and overlay binaries
2. When you rebuild after code changes, it kills the old agent process
3. Launches the new binary automatically
4. The desktop process reconnects to the refreshed IPC socket

This creates a **live‑code feedback loop** without manually restarting the GUI. The same mechanism applies to the overlay binary, enabling simultaneous iteration on multiple components.

## Step‑by‑Step Development Session

Follow these commands to start a fresh development session:

**1. Build and run the dev GUI**

```bash

# Using devenv (recommended)

devenv tasks run openlogi:gui

# Fallback using Cargo directly

cargo run -p openlogi-desktop

```

This creates the dev bundle, stops stale processes, and waits for the dev agent socket.

**2. Start the mock agent**

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

```

Spins up the hardware‑free agent with full device inventory.

**3. (Optional) Prevent automatic agent spawning**

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

```

Use when you already have a mock running and want to avoid rebuilding the embedded agent.

**4. Hot‑reload workflow**

Edit source files → run `cargo check` or `cargo run` → the dev runner automatically restarts the agent → GUI reconnects instantly.

## What You Can Develop Without Hardware

The mock agent enables complete feature development:

- **UI components** — Actions Ring, component gallery, settings panels
- **DPI and SmartShift** — write persistence and slider interactions
- **Lighting control** — RGB synchronization and effects
- **Camera‑linked behaviors** — automatic `camera_active` flag testing
- **Bolt pairing flows** — discovery, passkey entry, device addition

The mock's 30‑second `camera_active` rotation specifically supports testing foreground‑app detection and lighting automation.

## Key Source Files

Understanding these files clarifies how the development workflow operates:

| File | Purpose |
|------|---------|
| [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) | Overall workflow documentation, dev bundle behavior, hot‑reloading configuration |
| [`crates/openlogi-agent/src/bin/mock_agent.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/bin/mock_agent.rs) | Mock agent implementation and scripted inventory definition |
| [`crates/openlogi-desktop/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/lib.rs) | Desktop client connection logic for dev agent socket |
| [`crates/openlogi-agent-core/src/watchers/poll.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent-core/src/watchers/poll.rs) | File watcher implementation triggering hot‑reload |
| [`xtask/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/xtask/src/main.rs) | `devenv` task definitions (`openlogi:gui`, `openlogi:check`) |

## Summary

- The **dev app bundle** (`openlogi-dev` profile) automates process lifecycle management, ensuring clean agent/overlay startup
- The **mock agent** provides deterministic hardware simulation across mice, keyboards, receivers, and lighting devices without physical Logitech peripherals
- **Hot‑reloading** via file watching eliminates manual restart cycles, with automatic agent termination and socket reconnection
- Environment variables `OPENLOGI_PROFILE` and `OPENLOGI_ALLOW_EXTERNAL_AGENT` control socket selection and process coexistence
- The complete workflow enables hardware‑free development of DPI controls, SmartShift, lighting automation, and Bolt pairing flows

## Frequently Asked Questions

### How do I prevent the dev GUI from automatically spawning its own agent?

Set `OPENLOGI_DEV_AGENT=0` when running the desktop: `OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop`. This is useful when you want the GUI to connect to an already‑running mock agent rather than rebuilding and embedding a fresh agent binary.

### Can the mock agent simulate camera‑activated lighting behavior?

Yes. The mock flips a `camera_active` flag every 30 seconds on a rotating list of foreground applications. This triggers the same lighting automation logic that physical Litra devices would respond to, enabling testing of camera‑linked effects without actual video software running.

### What happens to configuration changes made to the mock agent?

All writes persist in memory for the duration of the mock process. DPI adjustments, SmartShift toggles, and lighting settings are retained and reflected in subsequent API calls, providing realistic state management for development and testing.

### How does hot‑reloading work when I modify agent code?

The dev runner watches the built binary via [`crates/openlogi-agent-core/src/watchers/poll.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent-core/src/watchers/poll.rs). When Cargo produces a new binary, the runner kills the old agent process, launches the new one, and the desktop GUI automatically reconnects to the refreshed IPC socket—typically completing within seconds.