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

> Learn how the NixOS module seamlessly starts the OpenLogi agent in your graphical session using a systemd user service that activates upon environment initialization.

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

---

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

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

```bash

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