A reproducible Matrix-inspired i3 desktop for local and XRDP sessions.
i3 Matrix packages the small desktop configuration I use in my homelab: i3, i3blocks, Rofi, Picom, GTK accents, terminal colours, wallpaper rotation and safe backup/restore helpers.
| Field | Current state |
|---|---|
| Maturity | 🟡 Active Development |
| Used in my homelab | ✅ Yes |
| Recommended for production | ❌ No |
| Setup difficulty | 🟡 Intermediate |
| Documentation | ✅ Complete for the current scope |
| Tested platform | Debian 13 with i3 and XRDP |
Important
The installer changes files in the current user's home directory, installs
Debian packages with sudo, and downloads Matrix-Icons. Existing managed
files are backed up first, but review the script and keep an independent
backup before using it.
This configuration grew from a personal Matrix desktop and was reduced to the parts that remain useful in a virtual workstation. Runtime state, editor data, cache, obsolete laptop widgets and hard-coded local paths were deliberately removed so the result can be reviewed and recreated later.
- Matrix black-and-green i3 profile with visible borders and gaps.
- Bottom i3blocks bar with time, CPU, memory, disk, volume and active network.
- Side-mounted Rofi launcher with Matrix-Icons.
- Conservative Picom/XRender configuration suited to XRDP.
- Wallpaper rotation for local, untracked images, with solid-black fallback.
Control+Shiftkeybindings that work through Guacamole on macOS.- Automatic, checksum-verified download of Matrix-Icons.
- Automatic backup of every managed file before installation.
- Restore helper for the latest desktop backup.
- No secrets, caches, shell profile changes or generated runtime state.
assets/ Banner, social preview and ecosystem badge
bin/ User commands installed in ~/.local/bin
config/ Application configuration
docs/ Theme notes and complete keybindings
themes/matrix/ i3, i3blocks, Rofi, Picom and GTK files
install.sh Dependency, icon theme and dotfile installer
restore.sh Backup restoration helper
Clone the repository and run the installer as the desktop user, not as root:
git clone https://github.com/issu-lab/i3-matrix.git
cd i3-matrix
./install.shThe script installs the required Debian packages, downloads Matrix-Icons from
the original openDesktop source, verifies the published MD5 checksum, stores
replaced files below ~/.local/state/i3-theme-backups/, and installs the full
Matrix profile. The installation fails safely if the icon archive cannot be
verified. Sign out and back in if i3 was not already running.
Restore the most recent desktop backup:
./restore.shPass a backup directory explicitly to restore a particular snapshot. Only files present in that backup are overwritten; files that had no predecessor remain.
- Debian 13 is the only tested distribution and the installer uses
apt-get. - Package names and i3/Picom syntax may require adaptation elsewhere.
- The installer is designed for a desktop user with
sudoaccess. - Personal wallpapers are deliberately excluded from the public repository.
- Automated end-to-end testing inside a clean graphical VM is not yet included.
The scripts and configuration are released under the MIT License. Third-party artwork and downloaded themes are excluded as documented in THIRD_PARTY_NOTICES.md.
This project is part of the iSSU Open Homelab ecosystem.
