You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 266ee30
Browse filesBrowse the repository at this point in the historyBrowse files
the readme showed no desktop and reached the file fourth
Three gaps, all above the fold.
No image anywhere, for a project whose output is a desktop. Someone
evaluating a distro looks for a screenshot before reading a word, and
found none. The niri shot goes directly under the tagline; its alt text
names the read-only overlay root fastfetch happens to be reporting,
since immutability making its own point for free is worth keeping.
The declaration appeared in section four, behind the principles, the
status note, and two full screens of install. "Your system is one file"
followed by instructions for installing a binary asks a reader to take
the pitch on faith until they scroll. The file moves directly under the
screenshot, and install now sits after the point where someone has
decided whether they care.
Nothing answered "why not Nix, why not Bluefin". Every informed visitor
asks inside ten seconds, and those are the ones worth converting. The
new section covers NixOS and Guix (same idea, and they had to build a
package universe to get it), Universal Blue (same three layers, but the
unit of configuration is which image you picked), and BlueBuild (builds
an image and stops at the image).
Deliberately not said: brew bundle cleanup has open reports of removing
what it never installed, which is the Bazaar incident 73771ab fixed,
class for class. One of those reports is macOS-specific and neither
proves it for flatpaks on Linux. The section makes the structural claim
instead, that cleanup decides what to remove from what is installed
rather than from what it installed. That is documented behaviour, it is
the actual distinction, and it keeps an unreproduced bug report out of
a README.
Two inline bolds became headings, since they now follow a section:
"Four principles, in order:" and "Status.". Neither body changed.
The screenshot lives in docs/screenshots/, not assets/. build.rs names
assets/ in rerun-if-changed, so a screenshot there would make every
image swap a rebuild.
135 tests. The two that read README.md still pass: the release asset
URL is untouched, and the first toml block is the same declaration it
was.
Copy file name to clipboardExpand all lines: README.md
+83-51Lines changed: 83 additions & 51 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,84 @@ You describe a machine in a small `kuma.toml`, and Kuma compiles it into a
9
9
bootable container image. Atomic updates and rollback come from bootc, and
10
10
the packages come from Fedora.
11
11
12
-
Four principles, in order:
12
+
13
+
14
+
## Your declaration
15
+
16
+
```toml
17
+
schema_version = 1
18
+
19
+
[system]
20
+
desktop = "niri"# curated sets: "niri" or "cosmic"; omit for headless
21
+
# base = "quay.io/fedora/fedora-bootc:44" # optional; see below
22
+
23
+
[user]
24
+
name = "me"
25
+
shell = "fish"
26
+
# password_hash = '$6$...' # from `kuma passwd`; applies only at creation
27
+
28
+
[packages]
29
+
rpm = ["fish", "distrobox", "tailscale"]
30
+
flatpak = ["org.mozilla.firefox"] # from Flathub, converged on boot
31
+
brew = ["ripgrep", "gh"] # CLI tools, no rebuild needed
32
+
33
+
[services]
34
+
enable = ["tailscaled.service"]
35
+
36
+
[snapshots]
37
+
enable = true# hourly read-only btrfs snapshots of /var/home
38
+
```
39
+
40
+
A fuller, commented version lives in
41
+
[`examples/`](examples/kuma.toml.example), and a test keeps every example
42
+
valid against the current schema.
43
+
44
+
**There is no base to name by default.** With `system.base` unset, kuma
45
+
composes its own from Fedora's package repos, starting from Fedora's
46
+
minimal bootc manifest: bootc, systemd, the kernel, dnf, and the hardware
47
+
enablement a real machine needs. Fedora stays the package source; kuma
48
+
builds no packages and no kernels. Name a `base` and kuma builds on that
49
+
image instead, as any bootc image can be.
50
+
51
+
`[system].firmware` trims the composed base to your hardware. Unset, it
52
+
ships every vendor's, so a machine that declares nothing about its own
53
+
still boots with working GPU, wifi, and audio. LVFS firmware updates
54
+
refresh on a timer; applying them stays a deliberate `fwupdmgr update`.
55
+
56
+
Machine state stays out of the file by default. Timezone and hostname
57
+
belong to the machine (`timedatectl`, `hostnamectl`) and survive image
58
+
updates; pin them here only when you want every machine built from this
59
+
file to match.
60
+
61
+
## How this differs
62
+
63
+
**NixOS and Guix** own the idea: one versioned file, convergence as the
64
+
only way to change anything, rollback for free. Getting there cost them
65
+
an entire package universe. Kuma keeps Fedora as the package source and
66
+
builds no packages and no kernels, so the declarative property arrives
67
+
without an ecosystem to rebuild. Nix's purity guarantees are what you
68
+
give up for that.
69
+
70
+
**Universal Blue** (Bluefin, Bazzite) ships the same three layers:
71
+
immutable base, flatpaks for apps, Homebrew for CLI tools. The unit of
72
+
configuration is which image you chose. Brewfiles now declare flatpaks
73
+
and formulae together, but `brew bundle` is a command you run rather
74
+
than a loop that runs without you, and its cleanup decides what to
75
+
remove from what is installed rather than from what it installed. Kuma
76
+
converges at boot and on a daily timer, and records what it installed,
77
+
so an app you added yourself stays yours and `kuma capture` offers to
78
+
write it down.
79
+
80
+
**BlueBuild** builds an image from a recipe and stops at the image. The
81
+
recipe never reaches the running machine. Kuma's keeps working after
82
+
install: `sync` converges, `diff` reports drift across file, image, and
83
+
machine, `kuma.lock` records what the last build resolved to, and
84
+
`capture` turns a change you made by hand into a proposal against the
85
+
declaration instead of an error to erase.
86
+
87
+
## Principles
88
+
89
+
In order:
13
90
14
91
1.**Simple.** The schema stays small and boring. Every field is a promise
15
92
kept forever, so new ones have to earn their place.
@@ -22,9 +99,11 @@ Four principles, in order:
22
99
legal next commands, never a dead end. The image carries the declaration
23
100
it was built from, so a machine can always speak for itself.
24
101
25
-
**Status.** Kuma is early. It builds, boots, and updates real hardware, and
26
-
it has not been run widely. Schema version 1 is meant to be permanent, so
27
-
the fields below are promises; everything around them can still move. `kuma switch`
102
+
## Status
103
+
104
+
Kuma is early. It builds, boots, and updates real hardware, and it has not
105
+
been run widely. Schema version 1 is meant to be permanent, so the fields
106
+
above are promises; everything around them can still move. `kuma switch`
28
107
reboots you into a system image, and `bootc` will roll a bad one back, but
29
108
try a declaration in `kuma vm` before a machine you depend on.
30
109
@@ -82,53 +161,6 @@ $ kuma switch --yes # bootc switch; takes effect on next boot
82
161
83
162
Without `--yes`, `switch` only prints what it would do.
84
163
85
-
## Your declaration
86
-
87
-
```toml
88
-
schema_version = 1
89
-
90
-
[system]
91
-
desktop = "niri"# curated sets: "niri" or "cosmic"; omit for headless
92
-
# base = "quay.io/fedora/fedora-bootc:44" # optional; see below
93
-
94
-
[user]
95
-
name = "me"
96
-
shell = "fish"
97
-
# password_hash = '$6$...' # from `kuma passwd`; applies only at creation
98
-
99
-
[packages]
100
-
rpm = ["fish", "distrobox", "tailscale"]
101
-
flatpak = ["org.mozilla.firefox"] # from Flathub, converged on boot
102
-
brew = ["ripgrep", "gh"] # CLI tools, no rebuild needed
103
-
104
-
[services]
105
-
enable = ["tailscaled.service"]
106
-
107
-
[snapshots]
108
-
enable = true# hourly read-only btrfs snapshots of /var/home
109
-
```
110
-
111
-
A fuller, commented version lives in
112
-
[`examples/`](examples/kuma.toml.example), and a test keeps every example
113
-
valid against the current schema.
114
-
115
-
**There is no base to name by default.** With `system.base` unset, kuma
116
-
composes its own from Fedora's package repos, starting from Fedora's
117
-
minimal bootc manifest: bootc, systemd, the kernel, dnf, and the hardware
118
-
enablement a real machine needs. Fedora stays the package source; kuma
119
-
builds no packages and no kernels. Name a `base` and kuma builds on that
120
-
image instead, as any bootc image can be.
121
-
122
-
`[system].firmware` trims the composed base to your hardware. Unset, it
123
-
ships every vendor's, so a machine that declares nothing about its own
124
-
still boots with working GPU, wifi, and audio. LVFS firmware updates
125
-
refresh on a timer; applying them stays a deliberate `fwupdmgr update`.
126
-
127
-
Machine state stays out of the file by default. Timezone and hostname
128
-
belong to the machine (`timedatectl`, `hostnamectl`) and survive image
129
-
updates; pin them here only when you want every machine built from this
130
-
file to match.
131
-
132
164
## Day 2
133
165
134
166
The file stays the interface. These read it or edit it for you:
0 commit comments