# How to Integrate the OpenLogi NixOS Module into Your System Configuration

> Integrate the OpenLogi NixOS module to install the package, manage udev rules, and control the openlogi-agent service. Streamline your NixOS setup with this comprehensive module.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`:

```nix

# 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:

```nix

# 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:

```nix

# 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:

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

};

```

### Step 4: Rebuild Your System

Apply the configuration with a standard rebuild:

```bash
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

```nix

# 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
        ];
      };
    };
}

```

```nix

# configuration.nix

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

```

### Custom Package Override

Replace the default package with your own build:

```nix
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:

```bash

# 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.