Introducing 0xTsoa: A Reproducible, Zero-Database Registry for Linux Desktops and Dotfiles

Linux desktop customization (often called "ricing") has a discoverability and reproducibility problem.

Great setups for Hyprland, Niri, Sway, i3, bspwm, AwesomeWM, KDE, and GNOME are scattered across Reddit threads,archived Gists, and unindexed GitHub repositories. When you finally find a setup you like, you often run into three issues:

Broken or floating references: The repository has moved on, screenshots no longer match the code, or the install instructions assume packages you do not have.
Unverified shell scripts: Many dotfile repositories ask you to pipe a remote install.sh directly into bash without a pinned commit or checksum.
Missing component search: Sometimes you do not want a full dotfile replacement. You only want a Waybar layout, a Quickshell or eww widget, a Rofi launcher theme, a SDDM login greeter, or a GTK theme.

To solve this, I built 0xTsoa (ZeroTsoa): an open-source, zero-database community registry for reproducible Linux desktop environments, dotfiles, and window manager setups across Wayland and X11.

Live Registry: https://0xtsoa.vercel.app
GitHub Repository: https://github.com/nyharena25/0xTsoa

What is 0xTsoa?

0xTsoa indexes both complete dotfile setups and individual Linux desktop building blocks across 17 categories (currently 173+ indexed configurations):

Window Managers and Full Setups: dotfiles, wm (Hyprland, Niri, Sway, River, i3, bspwm, dwm, AwesomeWM, Qtile, Hypr, XMonad, Labwc, Wayfire, Herbstluftwm, LeftWM, Openbox, GNOME, KDE Plasma, XFCE, Cinnamon)
Shells, Bars, and Panels: bar, widgets, dock, launcher, notifications
Visual Themes and Assets: gtk-theme, colorscheme, icons, cursors
System Screens and Utilities: login, lockscreen, boot, extension, tool, resource

Every entry in the registry is a human-readable, strictly typed JSON file stored inside the repository at configs/<author>/<slug>.json.

Why Zero-Database?

Running a community registry usually requires a PostgreSQL instance, an authentication layer, an API server, and ongoing hosting costs. If the maintainer stops paying for the database, the community index disappears.

0xTsoa runs with zero backend servers and zero databases. Everything is powered by Git, static JSON specifications, Astro build pipelines, and GitHub Actions:

1. Git as the Source of Truth

Every configuration lives in configs/<author>/<slug>.json and is validated against a strict Zod and JSON Schema specification (schema/config.schema.json). Anyone can fork, audit, or query the entire registry offline, or fetch the compiled static JSON index at https://0xtsoa.vercel.app/index.json.

2. Automated Issue-to-PR Submissions

Contributors do not even need to touch Git to submit a project. Filling out the New Project Submission GitHub Issue Form triggers an automated workflow (issue-to-pr.yml) that parses the form, computes any missing script checksums, validates the schema, and opens a ready-to-merge Pull Request.

3. GitHub Issues as the Voting Engine

Instead of a custom database table for upvotes, every indexed setup is paired with a dedicated GitHub Issue labeled vote. Community members react with positive reactions on the issue, and a prebuild script (fetch-votes.ts) compiles those counts into static build metadata to rank the Top 5 Spotlight on the homepage.

4. Nightly Upstream Synchronization

Dotfile repositories evolve constantly. Every night, a scheduled GitHub Actions workflow (sync-upstream.yml) checks all indexed upstream repositories via git ls-remote, advances pinned commit hashes to the newest default-branch commit, detects the latest release tag, and refreshes star counts automatically.

Security and Reproducibility by Default

Customizing your desktop should not mean trusting blind remote scripts. The 0xTsoa validator enforces three strict rules on every submission:

Immutable Source References: Floating branch names like main, master, or HEAD are rejected. Every config must pin source.ref to a specific Git commit hash or release tag.
Mandatory SHA-256 Checksums: If a setup references an external installer script (install.script), it must provide a verified 64-character SHA-256 digest (with a 1 MiB file size ceiling).
Structured Install Steps and Whitelisted Assets: Every project breaks its installation down into auditable deps, dotfiles, and reload commands, and all screenshots must come from allowlisted hosts pinned to immutable commits where supported.

The Tech Stack and "Paper & Ink" Design

Framework: Astro (Static Site Generation + Content Collections)
Language & Validation: TypeScript + Zod + JSON Schema (Draft-07)
Styling: Tailwind CSS v4 with a custom Neo-Brutalist "Paper & Ink" design system (#1E202B ink, #F4F1EA warm paper, #86DBCE cyan accent) designed for WCAG AAA contrast in both light and dark modes
Typography: Space Grotesk, Geist Variable, JetBrains Mono Variable, and custom BD Brick display glyphs
Search: Instant client-side multi-facet filtering paired with Pagefind for offline full-text search
Markdown Pipeline: Marked + sanitize-html with automatic rewriting of relative upstream repository paths and volatile GitHub attachment URLs