| 1 |
# Project Alloy |
| 2 |
|
| 3 |
*An opinionated, TUI-first tiling user layer for Fedora Silverblue.* |
| 4 |
|
| 5 |
## What Alloy is |
| 6 |
|
| 7 |
Project Alloy is to Silverblue what Omarchy is to Arch: a curated, beautifully-defaulted, keyboard-driven, tiling-first environment that fuses an immutable base, a Wayland compositor, an opinionated terminal-first stack, and a project-authored design system into one coherent system. The name is the thesis: an alloy is stronger than its component metals. |
| 8 |
|
| 9 |
Alloy is terminal-native. The one thing it authors is a ratatui design system and the `alloy` console built on it. Everything graphical it needs, it adopts. |
| 10 |
|
| 11 |
## What Alloy is not |
| 12 |
|
| 13 |
- Not a from-scratch package manager. Alloy lives on rpm-ostree. |
| 14 |
- Not a from-scratch distro. Alloy lives on Fedora Silverblue. |
| 15 |
- Not a ublue spin. Alloy is **alongside** Universal Blue (Bluefin, Bazzite, Aurora), not downstream of it; the name was picked specifically to avoid the ublue "Blue\*" prefix convention. |
| 16 |
- Not a gaming distro. The audience overlaps with Omarchy and Omakub, not with Bazzite. |
| 17 |
- Not a GNOME spin. Alloy's authored design system is custom-drawn (ratatui) and does not pick up libadwaita theming. |
| 18 |
|
| 19 |
## Audience |
| 20 |
|
| 21 |
Developers, keyboard-driven power users, Linux-native sensibility. People who would rather configure once than configure often, who prefer modern Rust tools over decades-old legacy ones, who live in the terminal, and who want the tiling-first immutable experience that no existing Fedora atomic variant currently delivers as a curated whole. |
| 22 |
|
| 23 |
The empty quadrant Alloy fills: |
| 24 |
|
| 25 |
|
| 26 |
|
| 27 |
| **GNOME** | Silverblue | Bluefin | |
| 28 |
| **KDE** | Kinoite | (none) | |
| 29 |
| **Tiling (Sway)** | Sericea | **Alloy** | |
| 30 |
| **Gaming** | (none) | Bazzite | |
| 31 |
|
| 32 |
Sericea and Kinoite are bare windowing on an immutable base with no opinionated user layer. Bluefin is GNOME-flavored developer experience. Bazzite is gaming. Alloy is opinionated tiling. |
| 33 |
|
| 34 |
## Guiding principles |
| 35 |
|
| 36 |
1. **Modern, well-featured, Rust-written tools.** When competitive Rust-native options exist, pick them. Where they don't, name the gap honestly and consider filling it. |
| 37 |
|
| 38 |
2. **Native to Alloy's design system, not native to GNOME.** Alloy authors in ratatui and maintains a design-system crate, `alloy_tui`: a palette, themed widgets, footer chrome, and reserved keys that the authored console and any future authored TUI pull from. Heterogeneity with adopted apps (sway's own chrome, swaylock, mako) is a knowing trade, not an accident. |
| 39 |
|
| 40 |
3. **Non-reactive by principle.** Alloy avoids the reactive UI pattern in everything it authors. State-to-view binding, declarative property graphs, async data trickling into UI components, the cluster of patterns that produces staged appearance, animation creep, hover-everywhere, and state-divergence bugs, is the "web-shaped feel" Alloy refuses on principle. ratatui is immediate-mode: it renders the whole frame from current state each cycle, making state divergence architecturally impossible. The same principle applies to any immediate-mode GUI toolkit. |
| 41 |
|
| 42 |
4. **Backwards compatible with hardware, not with software.** Same principle as `_meta`'s cross-cutting rule. Operators are expected to be on the current Alloy release; hardware support is broad. |
| 43 |
|
| 44 |
5. **Opinionated defaults; the configuration is the documentation.** Every default is a position we will defend in writing. |
| 45 |
|
| 46 |
6. **The console teaches the mental model.** The wedge is the `alloy` console: a terminal-native front door to the system, including a package view that makes Silverblue's install model legible. That model is the hardest thing about Silverblue and the thing GNOME Software does not address well. |
| 47 |
|
| 48 |
Silverblue presents it as three surfaces to choose between (rpm-ostree layered, Flatpak, distrobox), which is the problem rather than the model. Alloy replaces the choice with one **isolation dial**: `host` sees the full home and host integration, `workspace` sees its own home and the directories you name it, `sandboxed` sees what a portal hands it. The user picks how much a piece of software can reach, and Alloy picks the backend from that. Level is the stable interface, so a better backend can be repointed underneath it. |
| 49 |
|
| 50 |
`workspace` is the reason this is a model Alloy owns rather than a menu over two tools. Neither incumbent serves it: distrobox is all-in on host integration, flatpak all-in on sandboxing, and "a box that sees one project directory and nothing else" is what people want every time they run a package manager over someone else's code. It is also described as limiting blast radius, never as sandboxing. A rootless container with a bind mount is a speed bump. `sandboxed` is the only level with a real isolation model behind it, and the view has to say so rather than offer three interchangeable degrees of safety. |
| 51 |
|
| 52 |
## What we author vs what we adopt |
| 53 |
|
| 54 |
**Alloy authors** (in Rust): |
| 55 |
- `alloy_tui`, the ratatui design-system crate (palette, themed widgets, footer chrome, mock-or-real backend detection). It is the design system. |
| 56 |
- The `alloy` console (ratatui): info, services, storage, wifi/net, image swaps, generation rollback, a package view, and `alloy settings` schema-driven settings and config editing. See [CONSOLE.md](CONSOLE.md). |
| 57 |
|
| 58 |
**Alloy curates** (from upstream): |
| 59 |
- Fedora Silverblue as the base. |
| 60 |
- Sway as the compositor. |
| 61 |
- swaylock (lockscreen), mako (notifications), swaybar (bar): the graphical pieces a TUI cannot serve, adopted rather than authored. |
| 62 |
- The userland stack; see [STACK.md](STACK.md). |
| 63 |
|
| 64 |
## Status |
| 65 |
|
| 66 |
Pre-v0. This document is the project. Code follows. |
| 67 |
|