Red Pill - Backup & Restore for Omarchy

🎬 Video Demo

"You take the red pill, you stay in Hyprland and I show you how deep the rabbit-hole goes..."

A unified backup and restore system for Omarchy. Backs up configs and user data to external drives using rsync hardlink snapshots - each backup is a full browseable directory tree, but unchanged files are deduplicated via hardlinks so they use no extra disk space.

Features

• Three backup modes: configs only, user data only, or everything
• Rsync hardlink snapshots: space-efficient incremental backups on external drives
• TUI interface: whiptail-based menu with full CLI fallback
• Auto-backup on shutdown: systemd service runs a full backup every shutdown/reboot
• Backup verification: checksum manifests (xxh128 or sha256) with integrity checking
• New machine restore: standalone restore.sh written to the backup drive - works without Red Pill installed
• Username migration: automatically fixes paths when restoring to a different username/home directory
• Theme restoration: reapplies Omarchy theme after restore
• Login notifications: reminds you if no backup in 7+ days
• Walker integration: searchable from the Omarchy launcher
• Hyprland keybind: Super+Alt+B opens a floating TUI window

Requirements

• OS: Omarchy (Arch Linux)
• Dependencies: rsync, libnewt (whiptail), zstd, alacritty, desktop-file-utils (all ship with Omarchy)
• Backup destination: any external drive (ext4, NTFS, btrfs, exFAT, etc.)

Quick Start

git clone https://github.com/28allday/Red-Pill-Omarchy.git
cd Red-Pill-Omarchy
bash Redpill_update.sh

Then:

1. Press Super+Alt+B (or run redpill)
2. Set your backup destination (option 10)
3. Run your first backup
4. Optionally enable auto-backup on shutdown (option 11)

Usage

Keybindings

Action	Keybind
Open Red Pill TUI	Super + Alt + B
Search in launcher	Super + Space → type "RED PILL"

TUI Menu

The interactive menu provides:

Option	Description
1	Backup configs only (~/.config, ~/.ssh, ~/.gnupg, etc.)
2	Backup user data only (Documents, Pictures, Music, etc.)
3	Backup everything (configs + user data)
4	Restore (choose from snapshots or local backups)
5	List all backups (drive snapshots + local tarballs)
6	Delete backups (multi-select with confirmation)
7	Verify backup integrity (checksum validation)
8	Edit include list
9	Edit exclude list
10	Set backup destination (drive selection or manual path)
11	Toggle auto-backup on shutdown
12	Show paths and configuration

CLI Commands

redpill                          # Open TUI
redpill backup [configs|data|all]  # Run backup
redpill estimate [configs|data|all] # Dry-run estimate
redpill restore [SNAPSHOT|FILE]  # Restore from snapshot or tarball
redpill verify                   # Verify backup checksums
redpill list                     # List all backups
redpill config-backup            # Local config tarball (no drive needed)
redpill includes                 # Edit include list
redpill excludes                 # Edit exclude list
redpill destination              # Set backup destination
redpill where                    # Show all paths

Quick Restore (TTY)

bluepill

Shows the Matrix quote, then restores from the latest snapshot on your external drive (falls back to local backup if no drive found). Works from a TTY if your desktop is broken.

What Gets Installed

Redpill_update.sh installs the following:

Binaries

Path	Purpose
/usr/local/bin/redpill	Main TUI and CLI backup/restore tool
/usr/local/bin/bluepill	Quick restore shortcut (TTY-friendly)
/usr/local/bin/redpill-autobackup	Shutdown auto-backup wrapper
/usr/local/bin/redpill-notify	Login notification checker

Desktop Integration

Path	Purpose
~/.local/share/applications/redpill.desktop	User application menu entry
/usr/share/applications/redpill.desktop	System application menu entry
~/.config/walker/config.toml	Walker launcher custom command entry
~/.config/hypr/bindings.conf	Hyprland keybind (Super+Alt+B) + window rules
~/.config/hypr/autostart.conf	Login notification autostart

Systemd Service

Path	Purpose
/etc/systemd/system/redpill-autobackup.service	Runs full backup on shutdown/reboot

Config & State

Path	Purpose
~/.config/redpill/includes.conf	Paths to back up
~/.config/redpill/excludes.conf	Exclusion patterns
~/.config/redpill/destination.conf	Backup destination path
~/.config/redpill/RECOVERY.txt	Recovery guide
~/.local/state/redpill/backups/	Local config tarballs
~/.local/state/redpill/last_backup	Timestamp of last backup

How It Works

Backup Process

1. Estimate - dry-run rsync calculates total size, changed files, and new data to transfer
2. Snapshot - rsync copies files to a timestamped directory, hardlinking unchanged files to the previous snapshot
3. Checksums - xxh128 (or sha256) manifest generated in background for integrity verification
4. Latest symlink - atomically updated to point to the new snapshot
5. Standalone restore script - written to the drive root for new machine recovery

Snapshot Structure on External Drive

<drive>/redpill/
├── restore.sh                     # Standalone restore (no install needed)
├── latest -> snapshots/2026-02-08_14-30-00
└── snapshots/
    ├── 2026-02-08_14-30-00/       # Full directory tree
    │   ├── .config/               # All backed-up files
    │   ├── Documents/
    │   ├── backup.log             # Backup metadata and report
    │   └── checksums.xxh128       # Integrity manifest
    └── 2026-02-07_10-00-00/       # Previous snapshot (hardlinked)
        └── ...

Each snapshot is a complete, browseable copy. You can open any snapshot in a file manager and copy files manually if needed.

Hardlink Deduplication

If a file hasn't changed between backups, rsync creates a hardlink to the previous snapshot's copy instead of duplicating it. This means:

• Each snapshot looks like a full backup
• Only changed/new files consume additional disk space
• Deleting old snapshots is safe - files are only freed when all hardlinks are removed

Backup Modes

Mode	What's included
configs	~/.config, ~/.bashrc, ~/.bash_profile, ~/.ssh, ~/.gnupg, ~/.local/share/fonts, ~/.local/share/applications
data	~/Documents, ~/Pictures, ~/Music, ~/Videos, ~/Desktop, ~/Downloads, ~/Templates
all	Everything above combined

Default Exclusions

.cache/
.local/state/
node_modules/
__pycache__/
.Trash*/
*.tmp
*.swp
.thumbnails/

Auto-Backup on Shutdown

When enabled, a systemd service runs a full backup every time you shut down or reboot:

• Silently skips if no backup destination is configured
• Silently skips if the backup drive isn't mounted
• Silently skips if no first manual backup has been done
• 10-minute timeout to prevent hanging shutdown
• Kills rsync cleanly on SIGTERM

New Machine Restore

The standalone restore.sh on the backup drive works without Red Pill installed:

1. Install Omarchy on the new machine
2. Mount the backup drive
3. Run: bash /run/media/$USER/<drive>/redpill/restore.sh
4. Select a snapshot to restore
5. Reboot

The script handles username changes automatically by fixing symlinks and hardcoded paths in config files.

Login Notifications

redpill-notify runs on each Hyprland login and sends a desktop notification if:

• Auto-backup is enabled but no backup has ever been done
• The last backup was more than 7 days ago

Uninstalling

bash Redpill_uninstall.sh

The uninstaller removes:

• All binaries from /usr/local/bin/
• Desktop entries (user + system)
• Hyprland keybinding and window rules
• Hyprland autostart entry
• Walker custom command entry
• Systemd auto-backup service
• Optionally: config and state directories

Backup snapshots on external drives are never touched.

Troubleshooting

Backup destination not found

# Check if drive is mounted
lsblk

# Mount via udisks
udisksctl mount -b /dev/sda1

# Set destination manually
redpill destination

Auto-backup not running

# Check service status
systemctl status redpill-autobackup

# View last shutdown backup log
journalctl -u redpill-autobackup -b -1

# Ensure it's enabled
sudo systemctl enable redpill-autobackup

Verify backup integrity

redpill verify

Select a snapshot and the tool will check every file against its stored checksum.

Restore to different username

Both the TUI restore and standalone restore.sh automatically detect username changes and fix:

• Absolute symlinks pointing to the old home directory
• Hardcoded paths in config files under ~/.config/

Credits

• Omarchy - The Arch Linux distribution this was built for
• rsync - The engine behind hardlink snapshot backups

License

This project is provided as-is for the Omarchy community.