How the OpenLogi Dev-Run Workflow Integrates Cargo and Devenv

OpenLogi's dev-run workflow provides dual entry points—plain Cargo commands for lightweight iteration or Devenv tasks for reproducible environments—both converging on the same underlying Cargo build pipeline while automatically managing dev-agents and macOS app bundles.

The OpenLogi repository (AprilNEA/OpenLogi) orchestrates a sophisticated development experience that bridges standard Rust tooling with reproducible Nix environments. Understanding how the dev-run workflow unifies Cargo and Devenv allows developers to choose between rapid local builds or hermetic, environment-locked development without changing the underlying build logic.

Dual Entry Points: Plain Cargo vs. Devenv Tasks

OpenLogi offers two complementary approaches to trigger the dev-run workflow, each targeting different developer preferences while executing identical underlying binaries.

Plain Cargo runs directly against the system-installed Rust toolchain (managed via rustup) using standard workspace commands. Developers invoke cargo run -p openlogi-desktop, cargo test, or cargo build defined in the workspace's Cargo.toml and individual crate manifests. This path requires no Nix installation and uses the host environment's configuration.

Devenv Tasks provide a higher-level, reproducible environment that pre-configures exact toolchain versions, platform SDKs (including Xcode Metal), and auxiliary tools like sccache. According to the OpenLogi source code, Devenv executes the same Cargo commands but wraps them in Nix-provided isolation, ensuring bit-for-bit reproducibility across macOS and Linux machines. The tasks are defined in devenv.nix and automatically set environment variables like OPENLOGI_DEV_* before invoking Cargo.

Core Steps of the Dev-Run Execution Flow

The dev-run workflow operates through a five-stage pipeline that ensures consistent behavior regardless of the entry point chosen.

1. Environment Preparation

Developers begin by selecting their toolchain. Without Devenv, they ensure rustup provides the correct Rust version referenced in rust-toolchain.toml. With Devenv, they activate the shell via devenv shell, which automatically provisions the exact Rust compiler, linker, and SDKs specified in devenv.nix.

As documented in docs/DEVELOPMENT.md, the Devenv path exposes convenient task runners such as:

devenv tasks run openlogi:gui    # Launch desktop app with full env setup

devenv tasks run openlogi:check  # Run fmt, clippy, tests, and rustdoc

2. macOS Bundle Generation via Cargo Runner

When developing on macOS, the workflow intercepts standard Cargo runs to produce proper app bundles. The .cargo/config.toml defines a Cargo runner that forwards execution to xtask macos dev-bundle.

This stage creates target/dev/OpenLogi.app, a temporary application bundle containing the correct icon, bundle identifier, and metadata required for the GUI to appear as OpenLogi Dev in the Dock with proper macOS permissions. The runner script ensures the binary launches within this bundle structure rather than as a bare executable.

# Direct invocation of the bundle task

cargo run -p xtask -- macos dev-bundle

3. Automatic Dev-Agent Lifecycle Management

Each dev-run first terminates any orphaned dev-agent or overlay processes from previous sessions. It then rebuilds the openlogi-agent binary and starts it, waiting for the IPC socket to become available before launching the GUI.

This guarantees the UI connects instantly to the agent via the development IPC socket rather than falling back to production-fallback spawning logic. The agent binary resides in crates/openlogi-agent/ and implements the HID I/O contract required for Logitech device communication.

4. Profile Isolation

The dev-run workflow enforces strict separation between development and production data. It uses the openlogi-dev profile stored in ~/.config/openlogi-dev, ensuring that configuration files, single-instance locks, and IPC sockets do not collide with installed production builds.

Three environment variables control this behavior:

• OPENLOGI_DEV_AGENT – Controls whether the runner embeds the agent automatically
• OPENLOGI_DEV_BUNDLE – Indicates the bundle path for macOS
• OPENLOGI_PROFILE – Forces the specific profile directory

5. Hardware-Free Development Mode

For developers lacking Logitech hardware, the openlogi-agent-mock binary in crates/openlogi-agent/ implements the identical IPC contract as the real agent. This enables full UI development on unsupported machines.

To use the mock agent:

# Terminal 1: Start the mock agent

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

# Terminal 2: Launch GUI without auto-embedding agent

OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

Practical Dev-Run Commands

Quick Iteration with Plain Cargo

For rapid development cycles without Nix overhead:

# Build and run the desktop GUI

cargo run -p openlogi-desktop

# Run the full test suite across workspace crates

cargo test --workspace

Reproducible Builds with Devenv

For CI-matching builds or onboarding new team members:

# Enter the reproducible shell

devenv shell

# Run the GUI via Devenv task (handles env vars automatically)

devenv tasks run openlogi:gui

# Execute linting and documentation checks

devenv tasks run openlogi:check

Disabling Automatic Agent Embedding

To connect the GUI to an externally managed agent or the mock:

OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

Key Implementation Files

The integration between Cargo and Devenv relies on specific configuration files that orchestrate the workflow:

• docs/DEVELOPMENT.md – Comprehensive documentation of the Cargo vs. Devenv paths, dev bundle mechanics, and agent handling.
• .cargo/config.toml – Defines the macOS Cargo runner that forwards builds to xtask for bundle generation.
• devenv.nix – Nix expression providing the exact Rust version, sccache, and platform-specific SDKs (Xcode, Metal toolchain).
• xtask/ – Crate containing build utilities including the macos dev-bundle command invoked by the Cargo runner.
• crates/openlogi-desktop/ – Source for the GUI binary that connects to the dev agent via IPC.
• crates/openlogi-agent/ – Background agent binary owning HID I/O, including the openlogi-agent-mock variant.

Summary

• OpenLogi's dev-run workflow supports both plain Cargo (lightweight, system-dependent) and Devenv (reproducible, Nix-based) entry points.
• The Cargo runner in .cargo/config.toml automatically generates macOS app bundles via xtask macos dev-bundle, placing output in target/dev/OpenLogi.app.
• Automatic dev-agent handling rebuilds and launches the agent before the GUI, ensuring immediate IPC connectivity rather than production fallback behavior.
• Profile isolation via ~/.config/openlogi-dev and environment variables (OPENLOGI_DEV_AGENT, OPENLOGI_PROFILE) separates dev and production data.
• The openlogi-agent-mock binary enables development without physical Logitech hardware by satisfying the same IPC contract as the real agent.

Frequently Asked Questions

What is the difference between using plain Cargo and Devenv in OpenLogi development?

Plain Cargo executes directly against your system Rust toolchain installed via rustup, offering faster iteration but relying on your local environment configuration. Devenv provides a Nix-based reproducible shell that locks the exact Rust compiler version, SDKs, and tools like sccache, ensuring every developer and CI runner uses identical build conditions. Both execute the same underlying cargo run commands, but Devenv wraps them with additional environment variables and automatic setup.

How does OpenLogi handle macOS app bundling during development?

OpenLogi intercepts Cargo runs on macOS through a Cargo runner defined in .cargo/config.toml. This runner forwards the build to xtask macos dev-bundle, which assembles target/dev/OpenLogi.app with proper icons, bundle identifiers, and entitlements. This allows the GUI to appear correctly in the Dock as "OpenLogi Dev" with appropriate macOS permissions, rather than launching as a bare executable without bundle metadata.

Can I develop OpenLogi without owning Logitech hardware?

Yes. The repository includes openlogi-agent-mock, a binary in the openlogi-agent crate that implements the identical IPC contract as the physical device agent. Run the mock with cargo run -p openlogi-agent --bin openlogi-agent-mock, then launch the desktop GUI with OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop to connect to the mock instead of embedding the real agent. This enables full UI development on machines without supported Logitech devices.

How do I disable the automatic dev-agent embedding when running the GUI?

Set the environment variable OPENLOGI_DEV_AGENT=0 before launching the desktop application. For example: OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop. This prevents the Cargo runner from building and embedding the agent, allowing the GUI to connect to an externally launched agent (such as the mock agent or a separately managed debugging instance) via the IPC socket.

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