How the NixOS Module Starts the OpenLogi Agent in a Graphical Session

The NixOS module creates a systemd user service bound to graphical-session.target, automatically launching the OpenLogi background agent immediately after the graphical environment initializes.

The OpenLogi repository (AprilNEA/OpenLogi) includes a native NixOS module that handles agent deployment through systemd user units rather than manual configuration files. By integrating with the graphical session lifecycle, the module ensures the agent starts only when a desktop environment is active and shuts down cleanly when the session terminates. This implementation leverages standard systemd targets to provide a seamless "start-on-login" experience for NixOS users.

Systemd User Service Architecture

The NixOS module defines a user-level systemd unit named openlogi-agent within the systemd.user.services attribute set. According to the source code in packaging/linux/nixos-module.nix (lines 28-39), this unit manages the lifecycle of the background agent process.

Service Unit Definition

The service configuration specifies the binary execution and dependency relationships critical for graphical session integration:

• ExecStart: Points to the openlogi-agent binary derived from the configured OpenLogi package
• After: Set to [ "graphical-session.target" ] to ensure the agent starts only after the graphical environment is fully initialized
• WantedBy and PartOf: Conditionally bound to graphical-session.target when automatic startup is enabled

These settings create a managed process that respects the graphical session boundaries, ensuring the agent terminates when the user logs out of their desktop environment.

Graphical Session Lifecycle Binding

The integration relies on systemd's user session management and the special graphical-session.target unit that represents an active graphical desktop.

The launchAtLogin Option

The module exposes programs.openlogi.launchAtLogin, a boolean option defined at lines 17-22 in packaging/linux/nixos-module.nix that defaults to true. When enabled, this setting configures the service's WantedBy and PartOf directives to reference graphical-session.target.

This binding achieves two critical behaviors:

1. Automatic startup: The service starts whenever the graphical session target is reached
2. Clean shutdown: The service stops when the graphical session terminates, preventing orphaned background processes

If set to false, the service unit remains defined but lacks the graphical session dependency, requiring manual activation via systemctl --user.

Configuring the OpenLogi Module

Basic enablement requires only two lines of NixOS configuration:

{
  programs.openlogi.enable = true;
  # Automatic startup is enabled by default; explicitly disable if needed:

  # programs.openlogi.launchAtLogin = false;

}

The module automatically installs the openlogi-agent package and registers the systemd user service. The binary invoked by ExecStart originates from the OpenLogi agent crate, typically built from the repository's crates/openlogi-agent directory.

Manual Service Management

For debugging or manual control when automatic startup is disabled, interact with the user service using standard systemctl commands:

# Start the agent immediately

systemctl --user start openlogi-agent

# Check service status and recent logs

systemctl --user status openlogi-agent

# Restart the agent (useful after configuration changes)

systemctl --user restart openlogi-agent

These commands operate on the user bus rather than the system bus, ensuring the service runs within the context of the current graphical session.

Summary

• The NixOS module creates a systemd user service (openlogi-agent) defined in packaging/linux/nixos-module.nix
• programs.openlogi.launchAtLogin (default true) controls whether the service binds to graphical-session.target
• The service uses After, WantedBy, and PartOf directives to synchronize with the graphical session lifecycle
• The agent binary executes from the configured OpenLogi package only after the graphical environment initializes
• Users can manage the service manually via systemctl --user commands when automatic startup is disabled

Frequently Asked Questions

What triggers the OpenLogi agent to start automatically?

The WantedBy=graphical-session.target directive in the systemd user service causes the agent to start whenever the user's graphical session begins. This dependency is activated by default through the programs.openlogi.launchAtLogin option in the NixOS module.

How do I disable automatic startup while keeping the module enabled?

Set programs.openlogi.launchAtLogin = false; in your NixOS configuration. This removes the graphical-session.target binding from the service while preserving the service definition for manual activation with systemctl --user start openlogi-agent.

Why does the service use graphical-session.target instead of multi-user.target?

The graphical-session.target ensures the agent only runs during active graphical sessions and maintains proper integration with the user's desktop environment. The multi-user.target operates at the system level and lacks awareness of individual user desktop states, making it inappropriate for per-user graphical applications that require access to display servers or desktop buses.

Where is the systemd service definition located in the source code?

The service unit is generated dynamically by the NixOS module file at packaging/linux/nixos-module.nix (lines 28-39), which constructs the systemd.user.services.openlogi-agent configuration based on the evaluated module options rather than using a static unit file.

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