# How to Set Up a Development Environment for OpenLogi: Complete Guide > Easily set up your OpenLogi development environment. This guide covers Rust, Nix, and platform-specific tools for a smooth experience. - Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi) - Tags: getting-started - Published: 2026-08-28 --- **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: ```bash 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: ```bash sudo apt-get install libudev-dev libx11-dev libxrandr-dev libxdo-dev libxkbcommon-dev ``` **Optional but Recommended:** - **Nix package manager** (install from ) to use the `devenv` automation defined in `devenv.nix` and [`devenv.yaml`](https://github.com/AprilNEA/OpenLogi/blob/main/devenv.yaml). - **Git** for cloning the repository. ## Clone the Repository Fetch the source code from GitHub and enter the workspace directory: ```bash git clone https://github.com/AprilNEA/OpenLogi.git cd OpenLogi ``` The repository root contains the workspace [`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml), the `xtask` utilities for CI automation, and the [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/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: ```bash 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`](https://github.com/AprilNEA/OpenLogi/blob/main/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: ```bash 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: ```bash # 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: ```bash 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`](https://github.com/AprilNEA/OpenLogi/blob/main/.claude/skills/openlogi-macos-permissions/SKILL.md) in the repository. ### Linux Run the full desktop application: ```bash cargo run -p openlogi-desktop ``` To run only the background agent (useful for headless testing): ```bash cargo run -p openlogi-agent ``` The agent may require elevated privileges to access HID devices, or you can use the mock backend for testing: ```bash cargo run -p openlogi-agent --bin openlogi-agent-mock ``` The entry points for these executables reside in [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs) and [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/.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: ```bash 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`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml). - The **devenv** workflow via Nix automates dependency installation using `devenv.nix` and [`devenv.yaml`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) and [`xtask/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs), while the background agent entry point is at [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs). Both are built as separate binaries within the Cargo workspace.