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.shdirectly intobashwithout 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, orHEADare rejected. Every config must pinsource.refto 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, andreloadcommands, 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 (
#1E202Bink,#F4F1EAwarm paper,#86DBCEcyan 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-htmlwith automatic rewriting of relative upstream repository paths and volatile GitHub attachment URLs
Submit Your Setup or Contribute
If you maintain Linux dotfiles, a Waybar or Quickshell config, a custom theme, or a ricing utility, we would love to index your work in the registry:
- Explore the Live Registry: https://0xtsoa.vercel.app
- Browse the Catalogue: https://0xtsoa.vercel.app/catalogue
- Submit a Project (No Git Required): Open the New Project Issue Form
- Star or Fork on GitHub: https://github.com/nyharena25/0xTsoa
What window manager, compositor, or desktop environment are you running right now? Drop your setup or questions in the comments below!``
Top comments (2)
Hi Ny Harena! 👋🐧
First of all, congratulations on 0xTsoa! I really appreciate the idea of building a community-driven Linux desktop registry without introducing unnecessary databases or backend infrastructure.
Git as the source of truth, schema-validated configurations, and automated contributions make a lot of sense for this kind of project.
I downloaded your repository archive and examined the implementation, particularly the installation pipeline, upstream synchronization, validation logic, and GitHub Actions workflows.
I found several things worth discussing. 🔍
🔴 1. Installation scripts are not verified before execution
Status: Confirmed through source inspection.
In src/pages/configs/[author]/[slug].astro, the default installation command is generated as:
curl -fsSL <script-url> | bashHowever, your registry also stores SHA-256 checksums for external installation scripts.
The problem is that this generated command does not verify the downloaded content against the recorded checksum before execution.
Displaying a checksum and enforcing it are two different security guarantees.
An upstream script could change after validation, and the generated command would still execute whatever the URL currently serves.
Recommendation: Download the script to a temporary file, verify its SHA-256 against the pinned digest, and execute it only after successful verification.
This would better align the installation workflow with your security claims.
🟠 2. Nightly synchronization weakens reproducibility
Status: Confirmed architectural behavior.
In scripts/sync-upstream.ts, the synchronization process retrieves the upstream repository’s current HEAD and updates source.ref when a newer commit is available.
The scheduled workflow runs this automatically.
I understand the intention: keeping the catalogue fresh.
However, there’s an important distinction:
A reference can be immutable while the registry entry pointing to it remains mutable.
A configuration retrieved today may reference a different commit tomorrow.
That makes historical reproduction more difficult unless the exact registry revision is also preserved.
I’d consider separating two concepts:
New upstream commits could become update proposals rather than silently replacing previously approved references.
That would preserve both freshness and reproducibility.
🟠 3. Remote checksum verification is optional in the validation pipeline
Status: Confirmed through source and workflow inspection.
In scripts/validate-configs.ts, remote script verification is controlled by the --network flag.
The reviewed GitHub Actions workflows invoke:
npm run validatewithout enabling network verification.
Consequently, those validation runs do not independently download the current installation script and compare its bytes against the declared SHA-256.
The local schema checks are still valuable, but they establish a different property.
A correctly formatted SHA-256 value is not evidence that the referenced remote content matches it.
I’d recommend a separate, mandatory verification stage for submissions containing external installation scripts.
🟠 4. Issue-triggered script downloads need resource limits
Status: Source-level risk; exploitation not demonstrated.
In scripts/issue-to-config.ts, the Issue-to-PR conversion process can download an externally supplied installation script to calculate its SHA-256.
The reviewed fetch path does not specify an explicit timeout or enforce a streaming download-size limit.
This is particularly relevant because the workflow processes community-submitted GitHub Issues.
I’d recommend:
The separate network validator checks a 1 MiB limit, but it reads the response body before applying that check.
These observations do not establish a confirmed SSRF vulnerability or CI compromise. They identify boundaries that deserve stronger enforcement.
🟡 5. Installation commands remain a trust boundary
The registry supports structured installation steps containing shell commands.
This is useful for reproducibility and transparency, but a valid JSON document does not necessarily contain safe commands.
Schema validation establishes structural correctness, not behavioral safety.
I’d consider clearly distinguishing:
Schema validated
Source integrity verified
Installation behavior reviewed
These are three different levels of assurance.
A registry entry should not implicitly communicate the third simply because it satisfies the first.
✅ What I liked
There are also several positive architectural decisions worth acknowledging.
The repository contains 173 configuration JSON files, uses Zod and JSON Schema, and includes automated tests for important registry operations.
The Issue-to-PR workflow passes the issue body through an environment variable rather than directly interpolating it into a shell command.
The workflow also installs dependencies using npm ci --ignore-scripts, which is a sensible precaution when processing community submissions.
I particularly like the separation between structured metadata, static generation, and community contributions.
And using GitHub Issues for voting is an interesting way to avoid maintaining an additional application database.
🎯 My suggested priorities
I’d focus on three improvements before expanding the feature set:
P1: Make checksum verification part of the actual installation process.
P1: Preserve immutable, historically reproducible configuration revisions.
P2: Strengthen remote resource validation and download limits in community-triggered workflows.
After that, I’d expand automated tests around malicious or malformed submissions, upstream changes, checksum mismatches, and interrupted synchronization.
Final thoughts
I genuinely like the philosophy behind 0xTsoa.
Not every community platform needs a database, authentication service, and complex backend architecture.
Sometimes Git, static files, and a well-designed contribution workflow are exactly the right tools.
But reproducibility and security are properties that need to hold across the entire workflow, not just in the metadata format.
A pinned hash is useful. A verified hash is better. A verified hash enforced at execution time is where the security guarantee becomes meaningful.
One important limitation: this was a static review of the supplied repository archive. I haven’t executed the complete test suite, audited the deployed infrastructure, or demonstrated a successful exploit.
I’m sharing these findings as constructive engineering feedback, not as a claim that your service has been compromised.
Thank you for sharing the project and making the implementation available for review.
I hope these observations help strengthen 0xTsoa. Looking forward to seeing how it evolves!
Hi! Thank you so much for taking the time to inspect the codebase, dive into the GitHub Actions workflows, and write such an exceptionally thorough and constructive review.
This is hands down the most valuable technical feedback the project has received. You hit the nail on the head: there is a real gap between advertising reproducibility and cryptographic verification in the documentation versus strictly enforcing it across the entire runtime and ingestion pipeline.
I agree with all of your findings, and I am going to prioritize and implement your recommendations:
Enforcing checksum verification before execution (P1): You are completely right. Displaying a hash without verifying it before execution offers zero real protection against upstream tampering. I will update the generated deployment commands to download the script to a temporary location, verify it against the recorded digest, and only execute if the check passes cleanly.
Preserving immutable revisions vs upstream freshness (P1): This is a critical distinction that I overlooked. Silently mutating source.ref during nightly synchronization defeats historical reproducibility. I will separate the approved, immutable configuration revisions from latest upstream updates, turning new upstream commits into automated update proposals or PRs rather than in-place overwrites.
Mandatory network verification in CI: I will make the --network verification flag mandatory in the validation workflow for any submission containing external scripts, ensuring the declared SHA-256 matches the actual remote payload at review time.
Hard limits on issue-triggered script downloads (P2): I will update issue-to-config.ts to enforce strict request timeouts and a streaming byte limit that cuts off at 1 MiB before reading the full response into memory.
Clear assurance levels: I will update the UI and documentation to clearly distinguish between structural schema validity, hash pinning, and manual behavioral review so users know the exact boundaries of what has and has not been audited.
Do you have any other improvements, architectural ideas, or edge cases you would recommend keeping in mind as I implement these fixes?
If you are open to it, I would also welcome an issue or discussion on the repository (github.com/nyharena25/0xTsoa) so I can tag you for review once these changes land.
Thanks again for helping make 0xTsoa significantly more secure and reliable!