hyprmonitors/HOME-MANAGER.md

Home Manager Module for Hyprmonitors

This directory contains a Home Manager module for installing and configuring hyprmonitors, a Rust web server that provides an HTTP API for controlling Hyprland desktop monitors.

What is Hyprmonitors?

Hyprmonitors is a lightweight web server that exposes a RESTful API to control your Hyprland monitors using hyprctl dispatch dpms commands. It allows you to:

• Turn all monitors on/off via HTTP requests
• Control individual monitors by name
• Get current monitor status
• Integrate monitor control into web applications or scripts

Installation

Method 1: Direct Import

Add the module to your Home Manager configuration:

{
  imports = [
    /path/to/hyprmonitors/home-manager-module.nix
  ];

  # Enable Hyprland (required)
  wayland.windowManager.hyprland.enable = true;

  # Enable hyprmonitors service
  services.hyprmonitors.enable = true;
}

Method 2: As a Flake Input

Add hyprmonitors as a flake input in your flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    hyprmonitors.url = "path:/path/to/hyprmonitors";
  };

  outputs = { nixpkgs, home-manager, hyprmonitors, ... }: {
    homeConfigurations.youruser = home-manager.lib.homeManagerConfiguration {
      modules = [
        hyprmonitors.homeManagerModules.default
        {
          wayland.windowManager.hyprland.enable = true;
          services.hyprmonitors.enable = true;
        }
      ];
    };
  };
}

Configuration Options

The module provides several configuration options:

services.hyprmonitors = {
  enable = true;                    # Enable the service
  
  host = "127.0.0.1";              # Host to bind to (default: 127.0.0.1)
  port = 3000;                     # Port to bind to (default: 3000)
  
  logLevel = "info";               # Log level: error, warn, info, debug, trace
  
  package = pkgs.hyprmonitors;     # Override the package (optional)
  
  environmentVariables = {         # Additional environment variables
    HYPRLAND_INSTANCE_SIGNATURE = "your-signature";
  };
  
  settings = {                     # Future configuration options
    timeout_seconds = 30;
  };
};

Usage

Once installed and configured, the module provides several convenient tools:

Shell Aliases

The module automatically adds these shell aliases:

• hyprmonitors-start - Start the service
• hyprmonitors-stop - Stop the service
• hyprmonitors-restart - Restart the service
• hyprmonitors-status - Check service status
• hyprmonitors-logs - View service logs
• hyprmonitors-test - Test if the API is responding

API Helper Script

The hyprmonitors-curl script provides easy access to the API:

# Check if the service is running
hyprmonitors-curl health

# Get status of all monitors
hyprmonitors-curl status

# Turn all monitors on/off
hyprmonitors-curl on
hyprmonitors-curl off

# Control specific monitors
hyprmonitors-curl on DP-1
hyprmonitors-curl off HDMI-A-1

Manual API Access

You can also use curl directly:

# Health check
curl http://localhost:3000/health

# Monitor status
curl http://localhost:3000/monitors/status

# Turn all monitors on/off
curl -X POST http://localhost:3000/monitors/on
curl -X POST http://localhost:3000/monitors/off

# Control specific monitors
curl -X POST http://localhost:3000/monitors/DP-1/on
curl -X POST http://localhost:3000/monitors/HDMI-A-1/off

Service Management

The service is automatically managed by systemd:

# Check service status
systemctl --user status hyprmonitors.service

# View logs
journalctl --user -u hyprmonitors.service -f

# Manual start/stop (if needed)
systemctl --user start hyprmonitors.service
systemctl --user stop hyprmonitors.service

Integration with Hyprland

You can integrate hyprmonitors with Hyprland keybinds:

wayland.windowManager.hyprland.settings = {
  bind = [
    # Turn all monitors off/on
    "SUPER SHIFT, M, exec, hyprmonitors-curl off"
    "SUPER CTRL, M, exec, hyprmonitors-curl on"
    
    # Control specific monitors
    "SUPER SHIFT, 1, exec, hyprmonitors-curl off DP-1"
    "SUPER SHIFT, 2, exec, hyprmonitors-curl off HDMI-A-1"
    "SUPER CTRL, 1, exec, hyprmonitors-curl on DP-1"
    "SUPER CTRL, 2, exec, hyprmonitors-curl on HDMI-A-1"
  ];
};

Desktop Entry

The module creates a desktop entry "Hyprmonitors Control" that opens the health endpoint in your browser for quick access to verify the service is running.

Finding Monitor Names

To find your monitor names for use with the API:

hyprctl monitors

Common monitor names include:

• DP-1, DP-2 (DisplayPort)
• HDMI-A-1, HDMI-A-2 (HDMI)
• eDP-1 (Laptop screen)

Troubleshooting

Service won't start

1. Ensure Hyprland is running and properly configured
2. Check that the port isn't already in use
3. View logs: journalctl --user -u hyprmonitors.service

API requests fail

1. Verify the service is running: hyprmonitors-test
2. Check monitor names: hyprctl monitors
3. Ensure you're running commands in a Hyprland session

Permission issues

The service runs as your user and should automatically have access to Hyprland's IPC socket. If you encounter permission issues, ensure:

1. You're running the service as the same user running Hyprland
2. The XDG_RUNTIME_DIR environment variable is properly set

Security Considerations

• The service binds to localhost by default for security
• If you need remote access, change the host to 0.0.0.0 but ensure proper firewall configuration
• The service has restricted permissions and resource limits applied

Complete Example

See example-home-manager-config.nix for a complete working example configuration.

Requirements

• NixOS or Nix with Home Manager
• Hyprland window manager
• The module automatically handles all dependencies