How to Set Up a Development Environment for OpenLogi: Complete Guide

Setting up an OpenLogi development environment requires Rust 1.98+, optionally Nix with devenv for automated dependency management, and platform-specific build tools like Xcode on macOS or libudev-dev on Linux.

OpenLogi is a native, local-first alternative to Logitech Options+ written in Rust and organized as a Cargo workspace containing crates for the agent, UI, and device handling. To set up a development environment for OpenLogi, you must install the Rust toolchain, configure system-level dependencies, and initialize the workspace using either the automated Nix-based workflow or manual configuration according to the repository's official documentation.

Prerequisites

Before cloning the repository, ensure your system meets the minimum requirements for building the Rust workspace.

Rust Toolchain

OpenLogi requires Rust 1.98+ as the minimum supported Rust version (MSRV) and uses the 2024 edition. Install the latest stable toolchain via rustup:

rustup toolchain install stable
rustup default stable
rustc --version  # Verify 1.98 or higher

Cargo installs automatically with Rust and serves as the build system for the workspace.

Platform-Specific Dependencies

macOS:

• Xcode (via the App Store) is required for building the GUI components that use Metal shaders and GPUI.

Linux: Install the following development packages for UI and input-hook components:

sudo apt-get install libudev-dev libx11-dev libxrandr-dev libxdo-dev libxkbcommon-dev

Optional but Recommended:

• Nix package manager (install from https://nixos.org/download.html) to use the devenv automation defined in devenv.nix and devenv.yaml.
• Git for cloning the repository.

Clone the Repository

Fetch the source code from GitHub and enter the workspace directory:

git clone https://github.com/AprilNEA/OpenLogi.git
cd OpenLogi

The repository root contains the workspace Cargo.toml, the xtask utilities for CI automation, and the docs/DEVELOPMENT.md file containing the official development guide.

Configure Your Environment

Choose one of the following setup methods based on your preference for Nix automation or manual configuration.

Option 1: Using devenv with Nix (Recommended)

The repository provides a devenv configuration that automatically provisions the correct Rust version, system libraries, and development tools. From the repository root:

devenv up          # Builds and enters the development shell on first run

direnv allow .     # Optional: auto-activate environment when entering directory

Inside the devenv shell, all Cargo commands execute with the correct environment variables and dependencies pre-configured. The devenv.nix and devenv.yaml files in the repository root define the exact package versions and environment variables provided.

Option 2: Manual Setup

If you prefer not to use Nix, manually install the Linux dependencies listed above, then verify your Rust installation matches the workspace requirements:

rustup default stable
cargo --version

No additional configuration files are required, though you must ensure all system libraries are available in your PATH.

Verify the Build

Before running the full application, verify that the workspace compiles correctly by checking individual crates:

# Fast check of core types (no UI dependencies)

cargo check -p openlogi-core

# Verify agent orchestration logic

cargo check -p openlogi-agent-core

# Verify UI components (requires platform-specific GUI libraries)

cargo check -p openlogi-ui

If all checks pass without errors, your development environment is functional.

Run the Application

OpenLogi consists of multiple crates that can run independently or together.

macOS

Build and launch the desktop GUI:

cargo run -p openlogi-desktop

The application launches as a native macOS app. Grant Input Monitoring permissions in System Settings → Privacy & Security when prompted. For detailed permission troubleshooting, refer to .claude/skills/openlogi-macos-permissions/SKILL.md in the repository.

Linux

Run the full desktop application:

cargo run -p openlogi-desktop

To run only the background agent (useful for headless testing):

cargo run -p openlogi-agent

The agent may require elevated privileges to access HID devices, or you can use the mock backend for testing:

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

The entry points for these executables reside in crates/openlogi-desktop/src/main.rs and crates/openlogi-agent/src/main.rs.

Common Development Workflows

Execute these commands regularly during development:

• Run all tests: cargo test --workspace
• Test specific crate: cargo test -p openlogi-device
• Format code: cargo fmt --all -- --check
• Lint code: cargo clippy -p openlogi-core -- -D warnings
• Simulate CI pipeline: cargo xtask ci (defined in the xtask crate per xtask/AGENTS.md)
• Generate documentation: cargo doc --workspace --no-deps

Troubleshooting

Missing libraries on Linux: If compilation fails with linker errors, ensure you installed all Linux dependencies listed in the prerequisites section, particularly libudev-dev and libx11-dev.

Permission errors on macOS: The GUI requires accessibility permissions. Consult .claude/skills/openlogi-macos-permissions/SKILL.md for scripts that diagnose common permission issues.

Stale Nix cache: If using devenv and encountering environment inconsistencies, force a fresh build:

devenv up --recreate

Build failures on UI crate: Ensure you installed Xcode on macOS or the X11 development libraries on Linux before building openlogi-ui.

Summary

• OpenLogi requires Rust 1.98+ (MSRV) and uses a workspace layout defined in the root Cargo.toml.
• The devenv workflow via Nix automates dependency installation using devenv.nix and devenv.yaml.
• Manual setup requires installing platform-specific libraries like Xcode (macOS) or libudev-dev (Linux).
• Use cargo check -p openlogi-core for fast validation and cargo run -p openlogi-desktop to launch the GUI.
• Reference docs/DEVELOPMENT.md and xtask/AGENTS.md for extended documentation and CI automation.

Frequently Asked Questions

What is the minimum Rust version required for OpenLogi?

OpenLogi requires Rust 1.98 or higher as specified by the MSRV in the workspace Cargo.toml. The project uses the 2024 edition features, so older toolchains will fail to compile.

Can I develop OpenLogi without installing Nix?

Yes, Nix and devenv are optional. You can manually install Rust via rustup and install the platform-specific system libraries (Xcode on macOS, or libudev-dev/libx11-dev on Linux) to build the project using standard Cargo commands.

How do I run tests for a specific crate in the workspace?

Use the -p flag with Cargo to target specific crates. For example, cargo test -p openlogi-device runs only the device layer tests, while cargo test --workspace executes the full test suite across all crates including openlogi-core and openlogi-agent.

Where are the entry points for the desktop and agent applications?

The desktop GUI entry point is located at crates/openlogi-desktop/src/main.rs, while the background agent entry point is at crates/openlogi-agent/src/main.rs. Both are built as separate binaries within the Cargo workspace.

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