How to Integrate the OpenLogi NixOS Module into Your System Configuration

OpenLogi provides a complete NixOS module in packaging/linux/nixos-module.nix that installs the package, registers udev rules for Logitech devices, and manages the openlogi-agent user service via flake.nix exports.

The OpenLogi NixOS module integration process enables you to declaratively manage OpenLogi on NixOS systems. This open-source utility for Logitech HID++ devices exposes its module through the project's flake, allowing seamless incorporation into both simple and complex NixOS configurations.

Module Architecture and Components

The integration relies on two core files that work together to provide a complete NixOS experience.

packaging/linux/nixos-module.nix — Module Definition

This file declares the programs.openlogi option namespace with three configurable settings:

• enable — Activates the entire module block
• package — Specifies which derivation to install (defaults to the flake-built binary)
• launchAtLogin — Controls whether the agent auto-starts with graphical sessions

When enabled, the module performs three actions:

1. System packages — Adds openlogi to environment.systemPackages
2. Udev rules — Registers services.udev.packages with the project's 70-openlogi.rules
3. User service — Creates systemd.user.services.openlogi-agent attached to graphical-session.target

The service definition in lines 28-39 of nixos-module.nix sets wantedBy = [ "graphical-session.target" ] and partOf = [ "graphical-session.target" ] when launchAtLogin is true, ensuring the agent starts automatically with your desktop environment.

flake.nix — Flake Export and Package Build

The flake builds the openlogi Rust binary and exports the module under nixosModules.openlogi:

# From flake.nix lines 99-110

nixosModules.openlogi = {
  imports = [ ./packaging/linux/nixos-module.nix ];
  config.programs.openlogi.package = self.packages.${pkgs.system}.openlogi;
};

This structure lets you import the module while automatically using the flake-built package, or override it with your own derivation.

Step-by-Step Integration Process

Step 1: Add OpenLogi to Your Flake Inputs

Reference the GitHub repository in your system's flake inputs:

# flake.nix (your configuration)

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    openlogi.url = "github:AprilNEA/OpenLogi";
  };

Step 2: Import the NixOS Module

Bring the module into your system configuration through the imports list:

# configuration.nix or a module file

{ config, pkgs, inputs, ... }:
{
  imports = [
    ./hardware-configuration.nix
    inputs.openlogi.nixosModules.openlogi
  ];

Step 3: Enable and Configure OpenLogi

Activate the program with your preferred settings:

programs.openlogi = {
  enable = true;
  launchAtLogin = true;  # default: agent starts with graphical sessions

};

Step 4: Rebuild Your System

Apply the configuration with a standard rebuild:

sudo nixos-rebuild switch

After rebuilding, verify the integration:

• Binary available at /run/current-system/sw/bin/openlogi
• Udev rules at /run/current-system/etc/udev/rules.d/70-openlogi.rules
• Service status via systemctl --user status openlogi-agent

Complete Configuration Examples

Minimal Flake-Based Setup

# flake.nix

{
  description = "NixOS with OpenLogi Logitech device support";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    openlogi.url = "github:AprilNEA/OpenLogi";
  };

  outputs = { self, nixpkgs, openlogi, ... }:
    let
      system = "x86_64-linux";
    in {
      nixosConfigurations.desktop = nixpkgs.lib.nixosSystem {
        inherit system;
        modules = [
          ./configuration.nix
          openlogi.nixosModules.openlogi
        ];
      };
    };
}

# configuration.nix

{ config, pkgs, ... }:
{
  programs.openlogi = {
    enable = true;
    launchAtLogin = true;
  };
}

Custom Package Override

Replace the default package with your own build:

programs.openlogi = {
  enable = true;
  package = pkgs.callPackage ./my-openlogi-override.nix {};
  launchAtLogin = false;  # manual control only

};

The package option accepts any derivation producing a compatible openlogi binary with the expected bin/openlogi-agent executable.

Manual Service Control

When launchAtLogin = false, manage the agent manually:

# Enable and start immediately

systemctl --user enable --now openlogi-agent

# Check status

systemctl --user status openlogi-agent

# View logs

journalctl --user -u openlogi-agent -f

Key Source Files for Reference

File	Purpose
packaging/linux/nixos-module.nix	Module options and service definition
flake.nix	Package build, module export, integration tests
packaging/linux/package.nix	Rust binary derivation
packaging/linux/udev/70-openlogi.rules	HID++ device udev rules

Summary

• The OpenLogi NixOS module is exported via nixosModules.openlogi in the project's flake
• Enable with programs.openlogi.enable = true to install the package, udev rules, and user service
• Control auto-start behavior through the launchAtLogin boolean option
• Override the default package using the package option for custom builds
• The openlogi-agent service runs as a user systemd unit attached to graphical-session.target

Frequently Asked Questions

How do I disable automatic agent startup while keeping the package installed?

Set launchAtLogin = false in your configuration. The module still installs openlogi and registers udev rules, but the systemd service won't be wanted by graphical-session.target. Start it manually with systemctl --user start openlogi-agent when needed.

Can I use the OpenLogi NixOS module without flakes?

Yes, though it requires more effort. You would need to manually import packaging/linux/nixos-module.nix into your configuration and set config.programs.openlogi.package to a valid derivation. The flake-based approach is recommended as the upstream source of truth.

What system architectures does the module support?

The module inherits support from the underlying package.nix derivation. Check the flake's packages output for available systems—typically x86_64-linux and aarch64-linux based on the Rust toolchain configuration.

Where are the udev rules actually installed on my system?

The module adds them to services.udev.packages, which NixOS merges into /run/current-system/etc/udev/rules.d/70-openlogi.rules. These rules enable non-root access to Logitech HID++ devices, allowing the agent to communicate with your hardware without elevated privileges.

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