NitroOS

Modular Configuration Architecture

In Nitro OS, Hyprland settings are cleanly organized into modular configuration files under ~/.config/hypr/:

~/.config/hypr/
├── hyprland.conf            # Main compositor entrypoint & source loader
├── nitro/
│   ├── monitors.conf       # Multi-monitor layouts, HDMI, DisplayPort & scaling
│   ├── monitors.lua        # Lua module for dynamic monitor detection
│   ├── keybindings.lua     # Application & window management shortcuts
│   ├── autostart.lua       # Daemons (Waybar, Hyprpaper, Mako, Cliphist)
│   ├── look.lua            # Gaps, border gradients, blurs & rounding
│   ├── animations.lua      # Bézier curves & window transition physics
│   └── input.lua           # Touchpad gestures, keyboard layout & mouse speeds
└── scripts/                # Dynamic wallpaper and screenshot utilities

Monitors & HDMI Setup (nitro/monitors.conf & monitors.lua)

Whether you are connecting an external HDMI monitor, dual DisplayPort desk setup, or 4K ultrawide screen, configuring monitors in Nitro OS is done through declarative rules.

Step 1: Discover Connected Monitor Names

Run the query command in your terminal to see all plugged display ports:

hyprctl monitors

Monitor Syntax Breakdown

ParameterDescriptionExample Value
nameConnector port (e.g. HDMI-A-1, DP-1, eDP-1, or empty for fallback)HDMI-A-1
resolution@rateTarget resolution and refresh rate in Hz1920x1080@144 or 2560x1440@144
positionOffset coordinate XxY (e.g. 0x0 for primary, 1920x0 for right)1920x0 or auto
scaleDisplay scaling multiplier (1 for 100%, 1.25, 1.5 for HiDPI, 2 for 4K)1 or 1.25

Step 2: Add HDMI & Multi-Display Rules in /.config/hypr/nitro/monitors.conf

Open /.config/hypr/nitro/monitors.conf

and choose your setup layout:

monitor = eDP-1, 1920x1080@60, 0x0, 1
monitor = HDMI-A-1, 1920x1080@144, 1920x0, 1
monitor = , preferred, auto, 1

Lua-Based Dynamic Monitors (~/.config/hypr/nitro/monitors.lua)

If using the Nitro OS Lua module loader, monitors can be defined programmatically:

local hl = require("nitro.hypr")

hl.monitor({
  name = "eDP-1",
  resolution = "1920x1080@60",
  position = "0x0",
  scale = 1.0,
})

hl.monitor({
  name = "HDMI-A-1",
  resolution = "1920x1080@144",
  position = "1920x0",
  scale = 1.0,
})

hl.monitor_fallback("preferred", "auto", 1.0)

Step 3: Apply Changes Instantly

You do not need to log out or reboot. Reload the compositor configuration live:

hyprctl reload

Binding Workspaces to HDMI & External Displays

You can pin specific workspaces so code editors open on your primary monitor and communication apps stay on your HDMI display:

workspace = 1, monitor:eDP-1, default:true
workspace = 2, monitor:eDP-1
workspace = 3, monitor:eDP-1

workspace = 6, monitor:HDMI-A-1, default:true
workspace = 7, monitor:HDMI-A-1
workspace = 8, monitor:HDMI-A-1

Autostart Daemons (nitro/autostart.lua)

System services, background wallpaper daemons, clipboard history, and authentication agents:

exec-once = waybar
exec-once = hyprpaper
exec-once = mako
exec-once = /usr/lib/polkit-gnome/polkit-gnome-authentication-agent-1
exec-once = wl-paste --type text --watch cliphist store
exec-once = wl-paste --type image --watch cliphist store

Appearance, Gaps & Blurs (nitro/look.lua)

Customizing active window borders, Kawase background blurs, and corner rounding:

general {
    gaps_in = 6
    gaps_out = 12
    border_size = 2
    col.active_border = rgb(299C45) rgb(16291b) 45deg
    col.inactive_border = rgba(303a33aa)
    layout = dwindle
}

decoration {
    rounding = 12
    blur {
        enabled = true
        size = 6
        passes = 3
        new_optimizations = true
    }
    shadow {
        enabled = true
        range = 20
        render_power = 3
        color = rgba(0, 0, 0, 0.4)
    }
}