rustrland

Rust-powered window management for Hyprland

Features

• ⚡ Fast: Written in Rust for maximum performance and efficiency
• 🔒 Production-Ready: Memory-safe with comprehensive error handling and 48+ tests
• 🧩 Plugin-based: Modular architecture with hot-reload and animation systems
• 🔄 Compatible: Drop-in replacement for Pyprland configurations
• 📦 Easy deployment: Single binary, no Python dependencies
• 🎯 Multi-monitor: Intelligent caching with 90% API call reduction
• 🔧 Enhanced IPC: Robust reconnection logic and event filtering

Installation

Prerequisites

• Rust: Version 1.81 or newer (Install Rust)
• Hyprland: Compatible window manager (Install Hyprland)
• Environment: HYPRLAND_INSTANCE_SIGNATURE must be set (usually automatic)

Method 1: From Source (Recommended)

# Clone the repository
git clone https://github.com/mattdef/rustrland.git
cd rustrland

# Build and install
cargo install --path .

Method 2: Development Build

# Clone and build in debug mode
git clone https://github.com/mattdef/rustrland.git
cd rustrland
cargo build

# Run directly from source
cargo run --bin rustrland -- --help
cargo run --bin rustr -- --help

Method 3: Release Build

# Build optimized release version
cargo build --release

# Copy binaries to your PATH
sudo cp target/release/rustrland /usr/local/bin/
sudo cp target/release/rustr /usr/local/bin/

Verify Installation

# Check daemon version and features
rustrland --version

# Check client connectivity
rustr status

# Verify Hyprland connection
echo $HYPRLAND_INSTANCE_SIGNATURE  # Should show instance ID

Uninstall

To completely remove Rustrland from your system:

# Remove binaries (if installed via cargo)
cargo uninstall rustrland

# Or manually remove binaries (if copied to /usr/local/bin/)
sudo rm /usr/local/bin/rustrland
sudo rm /usr/local/bin/rustr

# Remove configuration files (optional - keeps your settings)
rm -rf ~/.config/hypr/rustrland.toml
rm -rf ~/.config/rustrland.toml
rm -rf ~/.cache/rustrland/  # Remove any cached data

# Remove from Hyprland autostart (if added)
# Edit ~/.config/hypr/hyprland.conf and remove:
# exec-once = rustrland --config ~/.config/hypr/rustrland.toml

# Kill any running daemon
pkill rustrland

# Clean up socket files
rm -f /tmp/rustrland-*.sock

Configuration

Overview

Rustrland supports dual configuration formats for maximum compatibility:

• Pyprland Format: [pyprland] - Full compatibility with existing Pyprland configs
• Rustrland Format: [rustrland] - Native format with enhanced features
• Dual Format: Both sections in one file - Rustrland merges them intelligently

Configuration Locations

Rustrland looks for configuration files in this order:

1. --config command line argument
2. ~/.config/hypr/rustrland.toml (primary)
3. ~/.config/rustrland.toml (alternative)
4. ./rustrland.toml (current directory)

Creating Your Configuration

Create your configuration file at ~/.config/hypr/rustrland.toml:

Basic Pyprland-Compatible Configuration

[pyprland]
plugins = ["scratchpads"]

[pyprland.variables]
term_classed = "foot --app-id"
browser_class = "firefox"
filemanager_class = "thunar"

[scratchpads.term]
command = "[term_classed] dropterm"
class = "dropterm"
size = "75% 60%"
animation = "fromTop"

[scratchpads.browser]
command = "firefox --new-window --class=[browser_class]"
class = "[browser_class]"
size = "90% 85%"
position = "center"

[scratchpads.filemanager]
command = "thunar --class=[filemanager_class]"
class = "[filemanager_class]"
size = "80% 70%"
position = "center"

Advanced Rustrland Native Configuration

[rustrland]
plugins = ["scratchpads", "expose", "workspaces_follow_focus", "magnify"]

[rustrland.variables]
term_classed = "foot --app-id"
browser_class = "firefox"
filemanager_class = "thunar"
music_class = "spotify"

# Enhanced scratchpad with all features
[scratchpads.term]
command = "[term_classed] dropterm"
class = "dropterm"
size = "75% 60%"
position = "center"
animation = "fromTop"
lazy = true
pinned = false
excludes = ["class:^org\\.gnome\\..*"]

# Multi-monitor aware scratchpad
[scratchpads.browser]
command = "firefox --new-window --class=[browser_class]"
class = "[browser_class]"
size = "90% 85%"
position = "center"
multi_monitor = true
preserve_aspect = true

# Mission Control-style expose (v0.3.0+ - Full Implementation)
[expose]
# Grid layout and visual settings
padding = 25                      # Padding between windows in pixels
scale = 0.3                       # Window scale factor (0.1-1.0)
show_titles = true                # Display window titles
background_color = "#000000CC"    # Semi-transparent overlay
highlight_color = "#FF6600"       # Selection highlight color

# Animation and performance
animation = "fromTop"             # Animation type (fromTop, fromBottom, etc.)
animation_duration = 250          # Animation duration in milliseconds
max_windows = 30                  # Performance limit (prevents slowdown)

# Advanced features
include_floating = true           # Include floating windows
include_minimized = false         # Include minimized windows
current_workspace_only = false    # Limit to current workspace
enable_caching = true            # Thumbnail caching for performance
mouse_selection = true           # Mouse click selection support
target_monitor = "auto"          # Target monitor ("auto", "DP-1", etc.)

# Multi-monitor workspace management
[workspaces_follow_focus]
follow_window_focus = true
allow_cross_monitor_switch = true
workspace_switching_delay = 100

# Viewport magnification
[magnify]
factor = 2.0
duration = 300
smooth_animation = true
min_zoom = 1.0
max_zoom = 5.0
increment = 0.5

Dual Format Configuration

# Legacy Pyprland section (for compatibility)
[pyprland]
plugins = ["scratchpads"]

[pyprland.variables]
term_classed = "foot --app-id"

# Enhanced Rustrland section (overrides and extends)
[rustrland]
plugins = ["scratchpads", "expose", "workspaces_follow_focus"]

[rustrland.variables]
browser_class = "firefox"  # Additional variables

# Scratchpad definitions (shared between formats)
[scratchpads.term]
command = "[term_classed] dropterm"
class = "dropterm"
size = "75% 60%"
animation = "fromTop"

[scratchpads.browser]
command = "firefox --class=[browser_class]"
class = "[browser_class]"
size = "90% 85%"

[expose]
padding = 20
scale = 0.2

Configuration Examples

The examples/ directory contains ready-to-use configurations:

• examples/pyprland-compatible.toml - Drop-in Pyprland replacement
• examples/rustrland-native.toml - Full Rustrland features
• examples/dual-config.toml - Hybrid configuration approach
• examples/advanced-animations.toml - Animation system showcase

Usage

Starting Rustrland

As a Daemon (Recommended)

# Start with default config location
rustrland

# Start with specific config file
rustrland --config ~/.config/hypr/rustrland.toml

# Start in foreground with debug output
rustrland --debug --foreground

# Start as background service
rustrland --config ~/.config/hypr/rustrland.toml &

Auto-start with Hyprland

Add to your ~/.config/hypr/hyprland.conf:

# Auto-start Rustrland daemon
exec-once = rustrland --config ~/.config/hypr/rustrland.toml

Client Commands

Scratchpad Management

# Toggle scratchpads
rustr toggle term        # Toggle terminal scratchpad
rustr toggle browser     # Toggle browser scratchpad
rustr toggle filemanager # Toggle file manager scratchpad
rustr toggle music       # Toggle music player scratchpad

# List and manage
rustr list              # List all available scratchpads
rustr status            # Check daemon status and uptime

Window Overview (Expose) - v0.3.0+ Enhanced

# Mission Control-style window overview with full navigation
rustr expose                 # Toggle expose mode with all windows in grid
rustr expose next           # Navigate to next window in sequence
rustr expose prev           # Navigate to previous window in sequence

# Advanced navigation (v0.3.0+)
rustr expose up             # Navigate up in grid
rustr expose down           # Navigate down in grid
rustr expose left           # Navigate left in grid
rustr expose right          # Navigate right in grid
rustr expose home           # Jump to first window
rustr expose end            # Jump to last window

# Selection and control
rustr expose select         # Select current window and exit
rustr expose select x y     # Mouse selection at coordinates
rustr expose status         # Show detailed status with metrics
rustr expose exit           # Exit expose mode without selection

Workspace Management

# Cross-monitor workspace switching
rustr workspace switch 1    # Switch to workspace 1 (on focused monitor)
rustr workspace switch 2    # Switch to workspace 2 (on focused monitor)
rustr workspace change +1   # Switch to next workspace
rustr workspace change -1   # Switch to previous workspace
rustr workspace list        # List all workspaces and monitors

Magnification/Zoom

# Viewport magnification
rustr magnify toggle        # Toggle zoom (1.0x ↔ 2.0x)
rustr magnify in           # Zoom in by increment (default 0.5)
rustr magnify out          # Zoom out by increment
rustr magnify set 3.0      # Set absolute zoom level
rustr magnify reset        # Reset zoom to 1.0x
rustr magnify status       # Show current zoom level

Command Line Options

Daemon Options

rustrland --help
  -c, --config <FILE>     Configuration file path
  -d, --debug            Enable debug logging
  -f, --foreground       Run in foreground (don't daemonize)
  -v, --version          Show version information

Client Options

rustr --help
  -h, --help            Show help message
  -v, --version         Show version information
  --socket <PATH>       Custom socket path

Keyboard Integration

Basic Keybindings

Add these to your ~/.config/hypr/hyprland.conf for essential functionality:

# Scratchpad keybindings
bind = SUPER, grave, exec, rustr toggle term        # Super + ` (backtick)
bind = SUPER, B, exec, rustr toggle browser         # Super + B
bind = SUPER, F, exec, rustr toggle filemanager     # Super + F
bind = SUPER, M, exec, rustr toggle music           # Super + M

# Window overview (Mission Control) - v0.3.0+ Enhanced
bind = SUPER, TAB, exec, rustr expose               # Super + Tab (toggle)
bind = SUPER, j, exec, rustr expose next            # Super + J (next window)
bind = SUPER, k, exec, rustr expose prev            # Super + K (prev window)
bind = SUPER, Return, exec, rustr expose select     # Super + Enter (select)
bind = SUPER, Escape, exec, rustr expose exit       # Super + Esc (exit)

# Workspace management
bind = SUPER, 1, exec, rustr workspace switch 1     # Super + 1
bind = SUPER, 2, exec, rustr workspace switch 2     # Super + 2
bind = SUPER, 3, exec, rustr workspace switch 3     # Super + 3
bind = SUPER, Right, exec, rustr workspace change +1 # Super + Right
bind = SUPER, Left, exec, rustr workspace change -1  # Super + Left

# Magnification
bind = SUPER, equal, exec, rustr magnify in          # Super + = (zoom in)
bind = SUPER, minus, exec, rustr magnify out         # Super + - (zoom out)
bind = SUPER, 0, exec, rustr magnify reset           # Super + 0 (reset)

# Utility
bind = SUPER, L, exec, rustr list                   # Super + L (list all)
bind = SUPER_SHIFT, S, exec, rustr status           # Super + Shift + S

Advanced Keybindings

# Expose navigation
bind = SUPER, j, exec, rustr expose next             # Navigate expose
bind = SUPER, k, exec, rustr expose prev             # Navigate expose
bind = SUPER, Return, exec, rustr expose select      # Select in expose
bind = SUPER, Escape, exec, rustr expose exit        # Exit expose

# Advanced workspace management
bind = SUPER_SHIFT, 1, exec, rustr workspace switch 1  # Force workspace 1
bind = SUPER_SHIFT, 2, exec, rustr workspace switch 2  # Force workspace 2
bind = SUPER_CTRL, Right, exec, rustr workspace list   # List workspaces

# Magnification control
bind = SUPER_SHIFT, equal, exec, rustr magnify set 2.0    # 2x zoom
bind = SUPER_SHIFT, 3, exec, rustr magnify set 3.0        # 3x zoom
bind = SUPER_SHIFT, 0, exec, rustr magnify toggle         # Toggle zoom

Installation Script

For automatic keybinding setup:

# Download and run the keybinding setup script
curl -sSL https://raw.githubusercontent.com/mattdef/rustrland/master/scripts/install-keybindings.sh | bash

See KEYBINDINGS.md for complete setup guide and alternative key schemes.

Troubleshooting

Common Issues

Daemon won't start

# Check Hyprland environment
echo $HYPRLAND_INSTANCE_SIGNATURE  # Should show instance ID

# Verify Hyprland is running
hyprctl version

# Check configuration syntax
rustrland --config ~/.config/hypr/rustrland.toml --debug --foreground

Client can't connect

# Check if daemon is running
rustr status

# Check socket permissions
ls -la /tmp/rustrland-*.sock

# Restart daemon
pkill rustrland
rustrland &

Scratchpads not working

# Test application command manually
foot --app-id dropterm  # Should work outside Rustrland

# Check window class detection
hyprctl clients | grep -i dropterm

# Verify configuration
rustr list  # Should show your scratchpads

Debug Mode

For detailed troubleshooting:

# Run daemon with debug output
rustrland --debug --foreground

# Check logs (if using systemd)
journalctl -f -u rustrland

# Verbose client output
rustr --debug toggle term

Development

Building from Source

# Clone and build
git clone https://github.com/mattdef/rustrland.git
cd rustrland
cargo build

# Run in development mode
cargo run --bin rustrland -- --debug --foreground

# Run client from source
cargo run --bin rustr -- --help

Development Commands

# Run comprehensive tests (48+ tests)
cargo test

# Run specific test suites
cargo test --lib scratchpads       # 20 scratchpad tests
cargo test --lib animation         # 16 animation tests
cargo test --lib enhanced_client   # Enhanced client tests

# Code quality
cargo fmt                          # Format code
cargo clippy -- -D warnings       # Lint (fails on warnings)

# Full CI pipeline
make ci                           # fmt + lint + test + build

Project Structure

rustrland/
├── src/
│   ├── main.rs              # Daemon entry point
│   ├── ...                  # Client entry point
│   ├── config/              # Configuration system
│   │   └── mod.rs           # Rustrland config
│   ├── core/                # Core daemon and plugin management
│   │   ├── daemon.rs        # Main daemon loop
│   │   └── ...              # Hot reload system
│   ├── ipc/                 # IPC communication
│   │   ├── mod.rs           # Hyprland IPC client
│   │   └── ...              # Unix socket server
│   ├── animation/           # Animation system
│   │   ├── timeline.rs      # Keyframe timelines
│   │   └── ...              # And more
│   └── plugins/             # Plugin implementations
│       ├── scratchpads.rs   # Production-ready scratchpads
│   │   └── ...              # And more
├── examples/                # Configuration examples
├── tests/                   # Integration tests
└── docs/                    # Documentation

Supported Plugins

• ✅ scratchpads: Production-ready dropdown terminals and applications with multi-monitor support (20/20 tests)
• ✅ expose: Mission Control-style window overview with grid layout and navigation (Integrated tests)
• ✅ workspaces_follow_focus: Multi-monitor workspace management with cross-monitor switching (Integrated tests)
• ✅ magnify: Viewport zooming and magnification with smooth animations (Integrated tests)
• ✅ shift_monitors: Shift workspaces between monitors with configurable direction (Integrated tests)
• ✅ toggle_special: Manage Hyprland special workspaces with multi-workspace support (Integrated tests)
• ✅ monitors: Advanced monitor management with relative positioning and hotplug support (15/15 tests)
• ✅ wallpapers: Hardware-accelerated wallpaper management with interactive carousel navigation (15/15 tests)
• ✅ system_notifier: Log monitoring with animated desktop notifications and Pyprland compatibility (10/10 tests)

Plugin Status Summary

Total: 6 production-ready plugins with 60+ comprehensive tests passing across all functionality.

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

🦀 Rustrland - Rust-powered window management for Hyprland