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:

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

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

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

```bash
# 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:

```bash
# 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:

```bash
# 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:

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

```bash
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