Noctalia Immich Wallpaper Plugin

A status bar plugin for Noctalia v5 that puts a photo icon in the bar. Click it to open a popup menu with quick Immich actions.

Features

• Native Immich Integration – fetches random images directly using the Immich API (no external CLI needed).
• Bar icon – a photo glyph lives in the bar; spins to a loader while the script runs
• Popup panel – click the icon to open a floating menu with:
  • Change Image – downloads a new random wallpaper and applies it
  • Open Immich – opens your Immich instance in the browser
• IPC bridge – the panel sends loading-state events back to the bar widget so the icon updates in real time
• Configurable via Nix – set your Immich URL and API key directly in your Home Manager configuration, or use the GUI.

Requirements

• Noctalia ≥ 5.0.0
• Internet connection to your Immich instance.

Plugin structure

noctalia-immich-wallpaper/
├── plugin.toml    ← manifest (widget + panel entries, settings)
├── widget.luau    ← bar icon script (onClick → togglePanel)
├── panel.luau     ← popup menu script (ui.* declarative UI)
└── wallpaper.png  ← plugin icon (optional)

Installation

With Nix & Home Manager

Add the flake to your inputs and import the module:

# flake.nix
inputs.noctalia-immich-wallpaper.url = "github:silverluke/noctalia-immich-wallpaper";

# In your home-manager configuration:
imports = [ inputs.noctalia-immich-wallpaper.homeManagerModules.default ];

programs.noctalia.plugins.immich-wallpaper = {
  enable = true;
  url = "https://immich.example.com";
  apiKey = "YOUR_API_KEY"; # Consider using sops-nix instead of hardcoding
};

Manual Installation

1. Link this folder into the Noctalia plugins directory:

   mkdir -p ~/.local/share/noctalia/plugins/
   ln -s ~/Projects/noctalia-immich-wallpaper \
         ~/.local/share/noctalia/plugins/noctalia-immich-wallpaper

2. In Noctalia Settings → Plugins, enable Immich Wallpaper Rotator.

Configuration

The plugin resolves your IMMICH_URL and IMMICH_API_KEY by checking the following sources in order of priority:

1. GUI Settings: Noctalia Settings → Plugins → Immich Wallpaper Rotator. (Note: Leave these blank to allow fallback to secrets/config files!)
2. Environment Variables: IMMICH_URL and IMMICH_API_KEY.
3. Config File: A simple KEY=VALUE file at ~/.config/immich-wallpaper/config.
4. NixOS/sops-nix Secrets: Raw files located at /run/secrets/immich-url and /run/secrets/immich-api-key.

Recommended NixOS Setup (with sops-nix)

If you use sops-nix, do not hardcode your credentials in programs.noctalia.plugins.immich-wallpaper.url. Instead, pass the secrets directly to /run/secrets:

# In your NixOS configuration (e.g. hosts/my-machine/configuration.nix)
sops.secrets = {
  immich-url = { owner = "luca"; };
  immich-api-key = { owner = "luca"; };
};

# In your Home Manager configuration
programs.noctalia.plugins.immich-wallpaper.enable = true;

With this setup, the plugin will automatically read the URL and API key securely on the fly.

Usage

1. Open Noctalia Settings → Desktop (or Lockscreen) to manage your widgets.
2. Drag the Immich Wallpaper bar widget onto your status bar.
3. Click the icon to open the popup panel.
4. Click Change Image to fetch and apply a random wallpaper from your Immich server.
5. Click Open Immich to launch the web interface in your default browser.

How it works

Bar icon (widget.luau)
  └── onClick()
        └── noctalia.togglePanel("silverluke/immich-wallpaper:menu")
              └── panel.luau: onChangeImage()
                    ├── noctalia.http() → fetch random asset ID
                    ├── noctalia.download() → save to ~/.cache/immich-wallpaper/wallpaper.jpg
                    └── noctalia.setWallpaper() → reload wallpaper in Noctalia