# Managing Kanshi with Systemd User Service

This guide explains how to configure `kanshi` as a `systemd` user service, ensuring it starts automatically with your `niri` Wayland session and runs reliably in the background. Using a `systemd` user service is generally preferred over simply running `kanshi &` in a startup script, as it provides better process management, logging, and automatic restarts if `kanshi` crashes.

## Prerequisites

*   **Kanshi Installed**: Ensure `kanshi` is installed on your system. If not, install it using your distribution's package manager (e.g., `sudo apt install kanshi` for Debian/Ubuntu, `sudo pacman -S kanshi` for Arch Linux).
*   **Kanshi Configuration**: You should have your `kanshi` configuration file set up at `~/.config/kanshi/config` as provided in the previous interaction.
*   **Systemd User Session**: Your `niri` session should be managed by `systemd` user services. This is typically the default for modern Linux distributions.

## Step 1: Create the Systemd User Service File

Create a new file named `kanshi.service` in your `~/.config/systemd/user/` directory. If the `user` directory doesn't exist, create it first:

```bash
mkdir -p ~/.config/systemd/user/
```

Then, place the following content into `~/.config/systemd/user/kanshi.service`:

```ini
[Unit]
Description=Dynamic output configuration for Wayland compositors
Documentation=man:kanshi(1)
PartOf=graphical-session.target

[Service]
Type=simple
ExecStart=/usr/bin/kanshi
Restart=always

[Install]
WantedBy=graphical-session.target
```

### Explanation of the Service File

*   **`[Unit]` Section**:
    *   `Description`: A human-readable description of the service.
    *   `Documentation`: Points to the `kanshi` man page for further information.
    *   `PartOf=graphical-session.target`: This directive ensures that `kanshi` is considered part of your graphical session. If your graphical session stops, `kanshi` will also stop. For `niri`, `graphical-session.target` is a suitable target to bind to, as `niri` is a Wayland compositor that typically runs within a graphical session [1].

*   **`[Service]` Section**:
    *   `Type=simple`: Indicates that the `ExecStart` command is the main process of the service.
    *   `ExecStart=/usr/bin/kanshi`: Specifies the command to execute when the service starts. This should be the full path to your `kanshi` executable.
    *   `Restart=always`: Configures `systemd` to automatically restart `kanshi` if it crashes or exits unexpectedly.

*   **`[Install]` Section**:
    *   `WantedBy=graphical-session.target`: This makes `kanshi.service` a dependency of `graphical-session.target`. When you enable the service, a symlink will be created, ensuring `kanshi` starts when your graphical session starts.

## Step 2: Reload Systemd Daemon

After creating or modifying a `systemd` unit file, you need to tell `systemd` to reload its configuration:

```bash
systemctl --user daemon-reload
```

## Step 3: Enable and Start the Kanshi Service

Now, enable the `kanshi` service so it starts automatically on login, and then start it immediately:

```bash
systemctl --user enable --now kanshi.service
```

*   `enable`: Creates the necessary symlinks for the service to start on boot.
*   `--now`: Starts the service immediately after enabling it.

## Step 4: Verify Service Status

To check if `kanshi` is running correctly as a `systemd` user service, you can check its status:

```bash
systemctl --user status kanshi.service
```

You should see output indicating that the service is `active (running)`.

## Important Considerations for Niri

For `kanshi` (and other Wayland-related services) to function correctly as `systemd` user services, your `niri` session needs to correctly set up the Wayland environment variables (`WAYLAND_DISPLAY`, `XDG_RUNTIME_DIR`). Most display managers (like GDM, SDDM, LightDM) and `niri` session scripts handle this automatically. If you encounter issues, ensure these variables are correctly exported in your `niri` startup process.

## References

[1] kanshi - ArchWiki. (n.d.). Retrieved from [https://wiki.archlinux.org/title/Kanshi](https://wiki.archlinux.org/title/Kanshi)