An independent, source-only Linux distribution built around one idea: you don't install a system, you craft one.
-
-
-
-
-
-
What Keru is
-
Keru (ける) is a Linux distribution where virtually nothing is decided for you. Every foundational component — init system, C library, filesystem, kernel, privilege-elevation tool, network stack — is a variable you resolve at install time. What lands on your disk is precisely what you chose, compiled from original source.
-
-
The name comes from ける・けいとうてき (keru keitō-teki), roughly "craft your system." It's the whole point stated as a phrase.
-
-
The three repositories
-
Keru is deliberately split into three pieces so each stays small and legible:
-
-
Repo
What it holds
-
KeruOS
This repo — the installer, profile system, build pipeline, and website.
-
kama
The package manager. A ~225-line shell script. The "kiln" that fires recipes.
-
kama-packages
The recipe repository — plain shell scripts that describe how to build each package.
-
-
-
Where it sits
-
Keru belongs to the line of source-and-choice distributions that includes Gentoo and Nix. Where Keru differs: it takes the "no opinion" stance further than any of them. Gentoo still picks most of your stack for you; Keru asks you to form the whole opinion up front, then builds exactly that.
-
-
Status
-
Keru is in active development. The first installable release, 0.1, will ship as a bootable ISO. Until then, the repositories document the design, philosophy, and the build pipeline it's all wired through.
-
-
- Anti-opinionated by design. Read the full reasoning in the philosophy.
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/web/anti-opinionated.html b/web/anti-opinionated.html
deleted file mode 100644
index 0cbd4b5..0000000
--- a/web/anti-opinionated.html
+++ /dev/null
@@ -1,66 +0,0 @@
-
-
-
-
-
-Anti-opinionated — Keru OS
-
-
-
-
-
-
-
-
-
-
The core stance, and what it actually grants and costs you.
-
-
-
-
-
-
Reading the room
-
Every Linux distribution is an answer to the same question: who decides what your system is? Most answers reduce to "the maintainers, wisely." Your distro picks systemd or OpenRC, glibc or musl, ext4 or btrfs, and you inherit that stack as the price of using it.
-
-
That's genuinely fine for a lot of people. It's how you get a system that mostly works with default effort. But it means the shape of your machine is decided by someone else's tastes, release cadence, and risk appetite.
-
-
The anti-opinionated answer
-
Keru answers differently: the distribution holds no position. Not a middle position — no position. It doesn't ship a "best" init or a "recommended" filesystem, because that recommendation is the very thing Keru exists to remove.
-
-
Every foundational component is presented as a flat, open choice in the installer. Runit or systemd? They're options, side by side, weightless. glibc or musl? Your call. btrfs or reiserfs or swap? All offered. Keru doesn't rank them, because ranking is an opinion, and opinions are exactly what it delegates to you.
-
-
What it grants
-
-
No inherited stack. You never fight a default you never agreed to. What's on the disk is what you chose, full stop.
-
Every system is the same system. "Your" configuration isn't a deviation from Keru's ideal — it is Keru. There's no blessed path and no lesser path.
-
The distro never defends a mistake. An opinionated distro inherits the burden of defending its picks forever. Keru inherits nothing to defend.
-
Legibility. Because there's no position to paper over, every choice is visible in make.conf — readable, editable, rebuildable.
-
-
-
What it costs
-
-
No hand-holding. There's no "the way you install Keru is the way you install Keru" comfort. You carry the decisions.
-
You must form an opinion. The installer's only requirement is that you have one. For people who specifically want that, it's freedom; it's not for everyone.
-
More surface to keep stable. Supporting many inits, libcs, and filesystems means more combinations to honor — which is why the stability promise is scoped honestly.
-
-
-
Not GNU/Hurd, not a meta-OS
-
To head off a common reading: anti-opinionated doesn't mean Keru is a "meta operating system" that runs arbitrary kernels. Keru is a Linux distribution. Its freedom lives in userspace and configuration — init, libc, filesystem, kernel (within Linux), tooling. It's the meta-distribution stance: choice and composition over a fixed opinionated stack.
-
-
In one line
-
An opinionated distro tells you what to use. Keru tells you that you have to choose — and then builds exactly what you pick.
The build pipeline is the machinery between your profile and a running system. It's intentionally thin — a few shell scripts that orchestrate Kama, not a build system monolith.
-
-
The stages
-
-
Stage 0 — bootstrap the toolchain
-
build-root.sh boots a toolchain from nothing: binutils, gcc, your chosen libc, then the toolchain package. This is the "fully from scratch" step — the stage that separates a source distro from one that seeds binaries.
-
-
Stage 1 — base system
-
The BASE_PACKAGES set from your profile is built and installed into $ROOT. Every package compiles against the stage-0 toolchain.
-
-
Stage 2 — the swappables
-
Exactly what you chose: the kernel ($KERNEL), the init system ($INIT), your privilege-elevation tool ($SUDO), and your network tools ($NET). Nothing preselected — the picks in your make.conf are the picks that get built.
-
-
Stage 3 — finalize the root
-
mkfs-root.sh formats and assembles the target as your chosen filesystem, producing the rootfs that will boot.
Shared helpers; knows the sibling-repo layout (KAMA_DIR, PKGS_DIR).
-
scripts/build-root.sh
The orchestrator — runs the four stages above.
-
scripts/mkfs-root.sh
Formats the target root as the chosen filesystem.
-
-
-
Convenience entrypoints
-
make rootfs # sh scripts/build-root.sh
-make install # sh installer/install.sh
-make live-init # syntax-check live/init
-make recipe-check # sh -n every recipe in kama-packages
-
-
The pipeline is the honest core of "from scratch": no binary base image, no opaque build tool — a shell script reading a profile and driving a shell package manager.
Keru holds one opinion — that you should form yours. That extends to the community: the interesting conversations here are about which init/libc/fs combos should be proven next, which recipes matter, and how the distro stays honest at its edges.
-
-
The stance carries over
-
-
No gatekeeping about your stack. Whatever init you run, you're a Keru user doing it right.
-
Bugs are bugs. Report a broken combination and it gets curated out of the "offered" set or proven and kept — not argued about for a release.
-
Small is fine. This isn't a race for the biggest community; it's a race for the most coherent one.
-
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/web/contact.html b/web/contact.html
deleted file mode 100644
index 3ebf2b2..0000000
--- a/web/contact.html
+++ /dev/null
@@ -1,63 +0,0 @@
-
-
-
-
-
-Contact — Keru OS
-
-
-
-
-
-
-
-
-
-
Keru is small and early, which means contributions are unusually consequential. A recipe you write may be the one a whole filesystem choice builds on. Here's how to get in.
-
-
Where things live
-
-
Repo
You'd contribute
-
KeruOS
Installer, profile, scripts, live init, docs, and this website.
-
kama
The package manager itself — and, ideally, not much. It's meant to stay small.
-
kama-packages
Recipes — the highest-leverage place. Busybox, runit, and a template exist.
-
-
-
Ways to help
-
-
Write recipes. A <pkg>.sh in kama-packages is a package. Start from TEMPLATE.sh. The format is small.
-
Test the toolchain bootstrap. The stage-0 build (gcc/glibc from nothing) is the riskiest seam; hands on real machines are gold.
-
Sharpen the installer. Menu UX, network handling, stability checks — all open.
-
Fix bugs. The road to 0.1 is literally a list of bugs between here and a booting ISO.
-
Docs & site. This website lives in web/ in the KeruOS repo — plain HTML, no framework. Improving it is plain work on plain files.
-
-
-
Ground rules
-
-
Match the ethos. Source-only, no opinion, small pieces. A PR that adds a dependency resolver to kama contradicts the project's spine.
-
Stay legible. If shell can do it plainly, don't introduce machinery.
-
Honesty at the edges. Unproven combinations go in with a warning, or not at all — never silently.
-
AGPL-3.0. All three repos are AGPL-3.0; contributions fall under it.
-
-
-
Where to start
-
Issues, recipe ideas, and bug reports live on the three repositories, and discussion on the contact channels. If you're looking for a first move: pick a recipe, read TEMPLATE.sh, and send it.
-
-
A small distribution values every PR — there's no pile to get lost in. What you send is likely to matter.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/web/credits.html b/web/credits.html
deleted file mode 100644
index da5c018..0000000
--- a/web/credits.html
+++ /dev/null
@@ -1,56 +0,0 @@
-
-
-
-
-
-Credits — Keru OS
-
-
-
-
-
-
-
-
-
-
Keru is the work of Astral (@AstralZX), who maintains all three repositories and this site. It grew out of earlier experiments (the lineage runs TOML packages → a 50-line build DSL → plain shell, and from opinionated dogmas to the anti-opinionated stance).
-
-
The tradition Keru sits in
-
-
Gentoo — source-based purity and the profile concept that Keru carries forward.
-
Nix — declarative, reproducible composition of a system from pieces.
-
Bedrock Linux — the "meta-distribution" idea: a distro about choice and composition.
-
OpenBSD & doas — the minimalism that Keru's default privilege tool comes from.
-
The skarnet suite (s6) — clean service supervision, an option among equals here.
-
-
-
The free software underneath
-
A source-only distribution is downstream of everyone who makes the sources it builds: the Linux kernel, GCC/binutils, the libcs, busybox, the init systems, the filesystem tools, and every project with a recipe in kama-packages. Credit belongs to all of them, and their licenses — not Keru's — govern those components. Keru's AGPL covers Keru's own code (see the license page).
-
-
This website
-
-
Fonts: Inter and JetBrains Mono.
-
Built: hand-written HTML/CSS/JS, no framework — consistent with the project's spine.
-
-
-
If you contributed and you're not listed, that's a bug — say so and it'll be fixed.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/web/docs.html b/web/docs.html
deleted file mode 100644
index f874119..0000000
--- a/web/docs.html
+++ /dev/null
@@ -1,50 +0,0 @@
-
-
-
-
-
-Docs — Keru OS
-
-
-
-
-
-
-
-
-
-
Keru is written ける in Japanese, and the project's full phrase is ける・けいとうてき (keru keitō-teki) — a system assembled the way you want it. The ethos is compact enough to sit behind a name: you don't receive a system, you craft it.
-
-
It's deliberately not a pronouncement. It's a description of the relationship Keru wants with you: you choose, it builds, and it has no agenda beyond honoring that choice.
-
-
The kiln and the craft
-
The package manager is called Kama (窯, "kiln"). The metaphor is warm on purpose — not a cathedral of machinery, but a kiln: you stack your ingredients, fire it, and what comes out is shaped by your hand, not by the kiln's preferences. A kiln doesn't have opinions about the pot. It just fires.
-
-
Principles guiding the work
-
-
Source-only. You run what you built. Every package is compiled from original source.
-
Legibility. Every decision is a script or a line in make.conf you can see and change.
-
Simplicity as stability. Fewer moving parts means fewer things to break — keeping the manager in shell is the point, not a compromise.
-
Honesty at the edges. Unproven combinations get a warning, not a wall. You are never lied to about risk.
-
No junk. No telemetry, no preinstalled opinions masked as defaults, no background assumptions.
-
-
-
What Keru is not
-
-
Not a meta-OS that runs arbitrary kernels — it's a Linux distribution that composes the bits above the kernel however you like.
-
Not an opinionless void — it holds one strong opinion: that you should form yours.
-
Not a challenge to pick the "right" stack — there is no right stack, there's only your stack.
-
-
-
企業はあなたの選択の上に成り立つ — the distro stands on your choices.
In the GNU/Linux world it names the Gentoo/Nix/Bedrock family: distributions organized around choice and composition of components rather than a fixed opinionated stack. Keru is the anti-opinionated member — its meta is choosing not to choose for you. Details.
-
-
Is Keru a "meta-OS" that runs any kernel?
-
No. Keru is a Linux distribution. Its freedom lives above the kernel — init, libc, filesystem, and Linux kernel variants. It won't boot a BSD or illumos kernel; that's not the claim and not on the roadmap.
-
-
How is this different from Gentoo?
-
Gentoo is source-based and highly configurable, but it still picks most of your stack and calls it defaults. Keru extends the same impulse to its logical end: no default init, no default libc, no default filesystem. And its manager, Kama, is a ~225-line shell script — no resolver, no database.
-
-
How is this different from Bedrock?
-
Bedrock stitches multiple distributions together (apt + pacman + xbps side by side). Keru doesn't compose distros — it composes components, one init/libc/fs/kernel/tool at a time, built from source.
-
-
Why is network required to install?
-
The ISO carries only the installer. Your entire system is fetched and compiled during install, so a connection is a hard gate. It's the price of "power to choose anything" — nothing is prebuilt. More.
-
-
Will my system be stable?
-
Stable on the combinations Keru offers you — that's the promise. If you pick something past the proven edge, the installer warns and lets you proceed. You're never blocked. The full stance.
-
-
Is this a joke or a real project?
-
Real. The repos are live, AGPL-3.0, and the road to 0.1 is documented. It's at the "design is public, nothing has booted hardware yet" stage — which is exactly what 0.1 is for.
-
-
What's with the Japanese?
-
ける (Keru) and ける・けいとうてき (keru keitō-teki) — "craft your system." Kama (窯) means "kiln." The naming is deliberate atmosphere, not branding gimmick. More.
-
-
Why is the package manager in shell?
-
Because a package manager should be legible, and shell is the most legible thing that can run a build recipe. The real cost of your build is the compiler, not the manager — so the manager gets to be simple.
The filesystem is how the kernel organizes data on disk — and it's a genuinely meaningdifferent choice: reliability vs features, volume management, snapshots, checksums, performance on specific workloads. Keru leaves it to you.
-
-
-
-
Filesystem
Character
-
ext4
The default. Proven, journaled, everywhere-supported, boring in the best way.
-
ext2 / ext3
Classic lineage — ext2 is unjournaled simplicity, ext3 added the journal.
-
btrfs
Snapshots, subvolumes, checksums, and a rich feature set out of the box.
-
xfs
Scale-friendly, robust, excellent for large files and heavy workloads.
-
zfs
Snapshots, RAID-Z, checksums, volume management. Serious features, more moving parts.
-
f2fs
Flash-friendly filesystem, designed for SSDs and flash storage performance.
-
jfs
IBM's journaled filesystem — lean, historically aimed at servers.
-
reiserfs
Once a pioneer; now effectively unmaintained. Offered, but flagged.
-
swap
As a separate swap area, part of the root setup.
-
-
-
-
Honest flags
-
Two filesystem options carry warnings in the installer:
-
-
zfs as root needs a kernel module + ZFS userspace, and isn't yet proven end-to-end in the 0.1 pipeline. Warned, not blocked.
-
reiserfs is unmaintained with no stable future. Offered because the choice is yours; flagged because honesty is cheaper than regret.
-
-
-
The filesystem tooling (mkfs, fs tools) is built alongside the kernel and init in stage 2 — your choice dictating exactly what gets compiled in.
Keru 0.1 ships as an ISO. There is no source build to DIY, no binary download, no flashing a rootfs tarball. Boot the ISO, answer the installer, and Keru builds exactly what you chose while you watch.
-
-
Before you begin
-
-
A working network. The build is fully online — every source tarball is downloaded fresh at install time.
-
A spare target disk.mkfs-root.sh formats whatever root device the installer points at. It will be written over.
-
Patience for the first build. Fetch + compile of the full toolchain and system takes a while on modest hardware.
-
Decisions. Prep your picks ahead — or just press enter; sane defaults are documented on every prompt.
-
-
-
The flow
-
1. Write the ISO to USB sudo dd if=keru-0.1.iso of=/dev/sdX bs=4M status=progress
-2. Boot the stick BIOS/UEFI → the live image starts by itself
-3. live/init mounts & runs the installer launches automatically on boot
-4. Connect to the network the installer runs nmtui for you when offline
-5. Make your picks init · libc · fs · kernel · sudo · net
-6. Keru builds the system fetch → stage 0 toolchain → base → swappables
-7. First boot your crafted system, exactly as chosen
-
-
Your picks
-
-
Choice
Default
Why you might change it
-
Init system
runit
systemd for optional use — but Keru never forces it.
-
C library
glibc
musl for a smaller static-leaning system.
-
Filesystem
ext4
btrfs snapshots, zfs features, xfs scaling.
-
Kernel
linux
linux-lts for longevity, hardened for attacks.
-
Privilege elevation
doas
sudo if you live in its muscle memory.
-
Network tools
nmtui
networkmanager, connman, or systemd-networkd.
-
-
-
Every option here has a dedicated page. See the swappables guide and its sub-pages before you install, so boot rehearsal is boring by design.
-
-
Day one
-
Keru installs a bare, honest base — the packages you chose plus the few kama needs to run. From there you shape the rest:
-
# your system, your way
-kama make vim # build anything else from source
-kama info busybox # peek at a recipe's metadata
-doas kama install tmux
-
Everything you don't install, you don't get. No services pretending to be useful, no telemetry phone-home.
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/web/index.html b/web/index.html
deleted file mode 100644
index e686f3a..0000000
--- a/web/index.html
+++ /dev/null
@@ -1,135 +0,0 @@
-
-
-
-
-
-Keru OS — craft your system
-
-
-
-
-
-
-
-
-
- independent · source-only · linux
- ける
-
You don't install a system. You craft one.
-
Keru is an anti-opinionated Linux distribution. Choose your init, libc, filesystem, kernel, and tools at install time — and it builds exactly what you chose from source. Nothing forced, nothing you didn't ask for.
Most distros hand you someone else's decision. Keru refuses that — every foundational component is yours to pick, resolved at install time and locked in at first boot.
The ISO carries only the installer. Boot it, it starts the installer automatically, you make your picks — and it builds your entire system from source, live.
-
-
keru@live:~$
-
[ keru ]Keru OS — craft your system
-Select the components, press enter for defaults.
-
-== Init system == [runit]
-== C library == [glibc]
-== Filesystem == [ext4]
-== Kernel == [linux]
-== Privilege elevation == [doas]
-== Network tools == [nmtui]
-
-Selecting: btrfs ← you choose, Keru builds it
-...fetching source...
-...compiling from scratch (gcc → glibc → the system)...
-[ keru ] rootfs ready: /tmp/keru/root
-[ keru ] you crafted a btrfs, doas, runit system. it boots.
-
-
-
-
-
-
-
why keru
-
Purist. Honest. Light.
-
-
~225
lines, kama package manager
-
0
binary packages
-
1,000+
possible system combos
-
0
opinions forced on you
-
-
-
Source-only
Everything — toolchain included — compiled from original source. No binary packages, no opaque machinery.
-
Kama, the kiln
The whole package manager is a ~225-line shell script. Legible. You can read every decision it makes.
-
Anti-opinionated
Keru's only opinion is that you must form one. After that, it shuts up and builds exactly what you chose.
-
From scratch
The ISO carries only the installer. Your system is fetched and built on the fly during install.
-
Warn, don't block
Stability is guaranteed on what's offered. Push past the proven edge and Keru warns you, then gets out of your way.
-
All yours
No telemetry, no unwanted services, no background assumptions. The disk reflects exactly what you chose.
-
-
-
-
-
-
-
Ready when it's ready.
-
Keru 0.1 will ship as a bootable ISO. No source builds, no manual tooling — boot, choose, then watch it craft your system.
The init system is the first thing that runs after the kernel — it boots the rest of your system and usually supervises services. It's also one of the most fought-over pieces of modern Linux. Keru's answer to the fight is simple: pick one yourself.
-
-
-
-
runit
Small, fast, BSD-style. Default in Keru — fast boot, simple service supervision, based on the runit process supervisor.
-
s6
The skarnet suite's init and service manager. Dependency-free, designed-for-service supervision, very small.
-
openrc
The classic Gentoo-style init. Compatible with sysvinit-style init.d, predictable "exclusive" service tree.
-
systemd
The dominant init — service manager, logind, udev, resolved, timedate, all in one. If you want it, it's a choice, not an assumption.
-
busybox-init
The bare init from busybox. Minimalist, tiny static binaries, closest to "nothing but a process supervisor."
-
sysvinit
The classic System V init. Simple runlevels, init.d scripts, historically the baseline Linux init.
-
dinit
A modern, fast, dependency-oriented init and service manager. Parallel boot, small footprint.
-
shepherd
GNU's service manager (init). Guile-based, declarative services, part of the GNU project.
-
-
-
-
Notes on pairing
-
Some combinations are easier than others. The stability check in the installer flags pairs that aren't yet proven (for example, musl + systemd), but never blocks them — the warn-not-block stance.
-
-
The init you pick is baked in at first boot. It's a choice you make once, deliberately, at install — not inherited from a default you never saw.
Boot the ISO. The installer starts itself. You choose. It builds.
-
-
-
-
-
-
The whole flow
-
Keru ships as a live ISO that carries only the installer. There is no prebuilt base image on the disk. The entire system — toolchain, kernel, init, libc, filesystem tooling — is fetched and compiled during installation, on the fly.
-
-
Network required. A working connection is a hard requirement for installing Keru. The installer checks it, and if you're not connected it offers to run nmtui for you.
-
-
Step by step
-
-
Boot the ISO. The live init (live/init) mounts the essentials and launches the installer automatically. No shell prompt, no manual boot gymnastics — it just starts.
-
Connect if asked. If there's no network yet, you'll be prompted. Say yes and nmtui opens; connect, then continue. The installer re-checks until you're online.
-
Choose your system. The installer walks through each swappable: init system, C library, filesystem, kernel, privilege elevation, network tools. Defaults are one enter-key away.
-
Resolve the stability check. Unproven combinations get a warning, never a block. If it's risky, you're told — then you decide.
-
Build. Confirm, and Keru fetches and compiles your exact system from source into a rootfs, then writes it to disk.
-
Boot what you chose. Fixed at first boot. The system that lands is precisely the one you designed.
Your choices are assembled into a make.conf, then handed to the build pipeline: scripts/build-root.sh drives Kama through toolchain bootstrap, base system, kernel, init, and tooling. The result — a rootfs matching your profile — is finalized with mkfs-root.sh and written to the target filesystem.
-
-
# Generated by keru-install — hand-tune then rebuild if you like.
-INIT=runit
-LIBC=glibc
-TARGET_FS=ext4
-KERNEL=linux
-SUDO=doas
-NET=nmtui
-LICENSE_ACCEPT=(*)
-
-
From scratch, every time. There's no binary base to seed. The toolchain is bootstrapped — gcc, binutils, your libc — then the rest on top. This is the "fully from scratch" path, kept honest.
The ISO carries only the installer. Everything else — toolchain, kernel, init, libc, tools — is fetched and compiled during install. No network, no install.
-
A machine that runs Linux
Keru is a Linux distribution. The installer boots on x86 (and other archs as they're proven).
-
A target disk/filesystem
The system is written to the filesystem you choose during install.
-
Some patience
Everything is built from source on your machine. A from-scratch toolchain + system takes time. The compiler, not the package manager, is the bottleneck.
-
A willingness to choose
Keru's only ask is that you form an opinion about init, libc, filesystem, kernel, and tooling. Defaults exist; the decisions are still yours.
-
-
-
Not requirements
-
-
No pre-existing Linux. You don't need an OS to install from — the ISO + installer handles everything.
-
No manual source builds. The installer drives the whole from-scratch build for you.
-
No binary packages. Nothing precompiled to download. You build what you run.
-
No telemetry or accounts. Nothing phone-home, nothing to sign up for to install.
-
-
-
The network, concretely
-
At the first installable release (0.1), the network path is straightforward: wired Ethernet via DHCP, or wireless via nmtui, both handled from inside the installer. See the network setup flow.
-
-
What "from the network" means
-
The installer fetches source tarballs (straight from upstream, or via a mirror when SOURCE_MIRROR is set) and pulls package recipes from the GitHub-hosted recipe repository. The heavy lifting is the compiler on your CPU — which is exactly the point of a source-only, from-scratch distribution.
-
-
If you want fast and prebaked, a binary distro is right there. If you want your machine — built from source to your exact selection — Keru is the one.
The live init starts installer/install.sh automatically on the console. If the installer ever exits (say you decline to build), it drops you into an emergency shell rather than stranding you.
-
-
1 — Network gate
-
Because the ISO carries only the installer, connectivity is checked first. The probe hits a few hosts (1.1.1.1, github.com) with ping; if ping isn't there, it falls back to a TCP connect via nc.
-
-
-
keru@live:~$
-
[ keru ] network: connected ← online, straight to choices
-or, if offline:
-[ keru ] warning: network: not connected
-Connect to the network now (runs nmtui)? [Y/n] y
-(nmtui opens; you connect; press ok)
-[ keru ] network: connected
-
-
-
If you press n at the prompt, the installer exits with a network connection is required to install Keru. If you run nmtui and don't actually connect, the loop simply asks again — it never fakes success.
-
-
2 — Choose your system
-
Each swappable is presented as a numbered menu. Pressing enter keeps the default; typing a number picks the option.
-
-
-
keru@live:~$
-
[ keru ] Keru OS — craft your system
-== Init system ==
- 1) runit
- 2) s6
- 3) openrc
- 4) systemd
- 5) busybox-init
- 6) sysvinit
- 7) dinit
- 8) shepherd
-Select [runit]:
-
-
-
The same pattern repeats for C library, filesystem, kernel, privilege elevation, and network tools.
[ keru ] warning: uclibc-ng + runit: not yet proven to build and boot together
-[ keru ] warning: this combination is unstable. Keru won't stop you — build at your own risk.
-
-
-
4 — make.conf
-
Your selections are written to a profile and shown back to you before anything builds:
-
-
-
keru@live:~$
-
[ keru ] writing /tmp/keru/make.conf
-[ keru ] profile complete:
-# Generated by keru-install — hand-tune then rebuild if you like.
-INIT=runit
-LIBC=glibc
-TARGET_FS=btrfs
-KERNEL=linux
-SUDO=doas
-NET=nmtui
-LICENSE_ACCEPT=(*)
-
-Build now? [y/N] y
-
-
-
5 — Build
-
Confirming hands the profile to the build pipeline, which runs in three stages:
-
-
Stage 0 — bootstrap.binutils, gcc, your chosen libc, then the toolchain package. This is the from-scratch toolchain.
-
Stage 1 — base system. The BASE_PACKAGES set from your make.conf.
-
Stage 2 — the swappables. Kernel, init, sudo-alternative, and network tools — exactly the ones you picked.
-
Stage 3 — finalize.mkfs-root.sh writes the chosen filesystem to the target root.
-
-
-
Result: a rootfs at /tmp/keru/root matching your profile, ready to boot. Fixed at first boot — the system you designed.
Kama's configuration is environment variables. Nothing to edit inside the script, nothing hidden — set them in the environment (export in a profile, or inline on the command line) and it's done.
-
-
Variables
-
-
Variable
Default
What it controls
-
PKGDIR
the kama-packages repo, sibling of the kama script
Where recipes are found.
-
ROOT
/tmp/keru/root
Where installed files land.
-
CACHEDIR
/var/cache/kama
Base for the dirty working dirs.
-
MAKE_CONF
/etc/kama/make.conf
Profile settings (JOBS, CFLAGS, etc.) if present.
-
SOURCE_MIRROR
unset
Mirror tried before upstream (set to e.g. mirror.example.org).
-
PURGE_TEMP_DEPS
1
Purge temp build deps after kama make.
-
JOBS
nproc
Parallel build jobs; recipes call make -j"$JOBS".
-
-
-
Cache layout
-
$CACHEDIR/
-├── dl/ downloaded archives
-├── src/ extracted source per package
-└── stage/ staged installs, committed to $ROOT on success
-
-
Common setups
-
# build into a scratch root
-ROOT=/mnt/keru-root kama make busybox
-
-# migrate cache to a big disk
-export CACHEDIR=/mnt/cache/kama
-export SOURCE_MIRROR=https://mirror.example.org
-
-# keep temp deps this run (default removes them)
-PURGE_TEMP_DEPS=0 kama make firefox
-
-
make.conf integration
-
Inside an installed Keru system, the profile at MAKE_CONF feeds the same variables into kama and the build scripts. Your make.conf reference lists the full set.
-
-
-
If MAKE_CONF exists it is sourced; missing is not an error.
-
The installer writes JOBS and CFLAGS from build-host detection.
-
Every variable has a sane default, so kama runs with zero config.
-
-
-
Zero-config by default, fully pointed overrides when you need them. That's the whole story — read on for recipes.
The package manager runs recipes. Here's what a recipe is.
-
-
-
-
-
-
A Kama recipe is a plain shell script. It declares metadata and defines build steps. There is no DSL to learn beyond shell itself — which is the point. The recipe repository (kama-packages) contains one file per package, and each one is readable top to bottom.
-
-
Anatomy of a recipe
-
name=busybox
-version=1.36.1
-url="https://busybox.net/downloads/busybox-${version}.tar.bz2"
-deps=( make )
-
-build() {
- cp ../config .config # basic setup from kama
- make -j"$(nproc)"
-}
-
-install() {
- make install CONFIG_PREFIX="$DESTDIR"
-}
-
-
The key fields:
-
-
Field
Meaning
-
name
Package name; used for the stage and cache paths.
-
version
The release version, typically embedded in the url.
-
url
Upstream source tarball (mirror-then-upstream on fetch).
-
deps
Array of build-time dependencies, built then purged.
-
build()
Runs in the extracted source dir — configure & compile.
-
install()
Installs into the package's stage dir (DESTDIR).
-
-
-
Two tiers
-
Recipes can stay deliberately simple or take full control:
-
-
Easy tier — the build() / install() sugar above. Great for "configure, make, make install" packages.
-
Advanced tier — pkg_build(), pkg_install(), custom pkg_fetch(), and a pkg_post() hook. For packages that need a hand.
-
-
-
Kama maps the easy tier onto the advanced one when the advanced forms aren't defined, so simple recipes stay simple and complex ones stay powerful.
-
-
The staging model
-
Building installs into a per-package stage dir, not the live root. That's how kama can assemble a complete system in $ROOT — the installer's whole trick — without ever touching the tree being built. The install step copies the staged dir into $ROOT.
-
-
How it's found
-
Kama locates a recipe by trying PKGDIR/<pkg>/PKGBUILD, then PKGDIR/<pkg>.sh, then PKGDIR/<pkg>/*.sh. Naming a recipe file <pkg>.sh is the common case.
-
-
A recipe is a contract you can read. No opaque package format, no hidden build logic — if you can read shell, you can audit every package in the repository.
Keru splits its world into three repositories so each stays small and legible. The package side of that is:
-
-
-
Repo
Holds
Keeps
-
kama
The manager — the kama entry point and lib/kama.sh core.
The code.
-
kama-packages
The recipe repository — one .sh per package.
The knowledge.
-
KeruOS
The OS: installer, profile, build pipeline, live init, website.
The orchestration.
-
-
-
Where the repos live
-
github.com/AstralZX/kama # the manager (canonical)
-github.com/AstralZX/kama-packages # the recipe repository (canonical)
-github.com/AstralZX/KeruOS # the OS itself (canonical)
-
-git.spectoria.dev/AstralZX/kama # mirror
-git.spectoria.dev/AstralZX/kama-packages # mirror
-git.spectoria.dev/AstralZX/KeruOS # mirror
-
The canonical host is GitHub. Mirrors of all three repos now live on git.spectoria.dev. They are read-mirrors — push and issues stay on GitHub, and the mirrors can fall behind by however long it's been since the last sync. A Codeberg mirror is also under consideration.
-
-
No package recipes ship on the ISO, in the installer, or anywhere else. The recipe repository on GitHub is how you get packages — clone it or install Keru, which fetches it at build time.
-
-
Why separate
-
-
Independent cadence. The manager changes rarely; recipes change constantly. Mixing them couples an ossified core to churn.
-
Clear ownership. "Which file builds busybox?" — the recipe repo. "How does kama decide to stage?" — the manager repo. No guessing where things live.
-
Small repos, legible diffs. A PR adding a package touches exactly one file in one repo.
-
Cross-repo defaults. Keru's scripts expect the three repos as siblings (kama next to kama-packages next to KeruOS), and every path is overridable via KAMA_DIR / PKGS_DIR.
-
-
-
How they fit together
-
# KeruOS build-root.sh drives kama against kama-packages
-KAMA="$KAMA_DIR/kama" # the manager
-PKGDIR="$PKGS_DIR" "$KAMA" make "$pkg" # a recipe, executed
-# into $ROOT — a completed system, built from source.
-
-
The installer is the conductor: it writes your make.conf, then calls the build pipeline, which runs kama over recipes to produce exactly the system you chose.
-
-
This is Keru's answer to packaging sprawl: three tiny repos, each human-sized, instead of one monolith that swallowed everything.
Kama's commands are few on purpose. Here's the complete set:
-
-
-
Command
What it does
-
kama fetch <pkg>
Download and extract source for a package into the cache.
-
kama build <pkg>
Stage-build one package (configure/make) into its stage dir.
-
kama install <pkg>
Build + install a package into $ROOT (staging-aware).
-
kama make <pkg>
High-level: fetch deps, build, install, then purge temp deps.
-
kama purge [pkg ...]
Remove temp build-time deps after a successful install.
-
kama info <pkg>
Show a recipe's metadata (name, version, url, deps).
-
kama help
Print the command reference.
-
-
-
Making a package, end to end
-
kama make is the command that ties it together. For a package with dependencies it walks through:
-
-
$ kama make firefox
-
[ kama ] building temp deps for firefox: rust gtk3
- ... fetch, build, install each temp dep ...
-[ kama ] building firefox
- ... stage build + install into $ROOT ...
-[ kama ] purging temp deps for firefox: rust gtk3
-
-
-
Environment & config
-
Kama reads a few things to know where to work:
-
-
Variable
Default
-
PKGDIR
The recipe repo (kama-packages, sibling by default).
-
MAKE_CONF
/etc/kama/make.conf — profile settings, if present.
-
ROOT
/tmp/keru/root — where installed files go.
-
CACHEDIR
/var/cache/kama — source, download, and stage dirs.
-
PURGE_TEMP_DEPS
1 — whether temp deps are purged after building.
-
-
-
Fetch details
-
-
Mirror first. Downloads try SOURCE_MIRROR before upstream, so a mirror you run can carry the load.
-
Cached. Already-downloaded source is reused; already-extracted source isn't re-extracted.
-
Auto-extract. Tar (gz/xz/bz2/plain) and zip are handled automatically by extension.
-
-
-
Kama's surface stays tiny because the complexity lives in recipes, not the manager. Read how recipes work next.
Kama (窯, "kiln") is Keru's package manager. It's a pure-shell script of roughly 225 lines that builds every package from source by running the commands in a recipe. It holds no opinions — matching the distro that ships it. It reads a make.conf, runs recipe commands, and gets out of the way.
-
-
-
-
no dbNo package database
Kama doesn't track installed files in a manifest db. It stages, installs, and moves on.
-
no resolverNo dependency resolver
Dependencies come from the recipe's deps[] array — explicit, not discovered.
-
shellPure shell
The whole manager is a script. Legible end to end; every decision is something you can read.
-
stageStaging installs
Builds into a per-package stage dir, then copies into $ROOT — never smears the live tree.
-
tmp depsEphemeral build deps
Build-time-only dependencies are fetched, built, installed, and purged after use — they never accumulate.
-
$ROOTBuilds anywhere
Targets $ROOT, so it can assemble a full system in a staging root — exactly what the installer needs.
-
-
-
-
The philosophy in the manager
-
Kama embodies Keru's central bet: package managers became more complex than the packages they manage. A resolver, a database, a binary format, a compiled daemon — none of that is needed to honestly manage a source-built system. What's needed is a script that faithfully runs what a recipe says, so the user can read any decision it makes.
-
-
"A package manager doesn't need a resolver to be honest. It needs to be legible — you can read every decision it makes, because every decision is a script or a line in make.conf you can see and change."
Keru is a Linux distribution — but "Linux" is a family, and the kernel is genuinely a choice: freshness vs stability, hardening vs performance, general-purpose vs tuned. Keru ships the choice, not the verdict.
-
-
-
-
linux
The default. Stock mainline — the broad, well-trodden baseline that matches the ecosystem.
-
linux-lts
The long-term-supported line. Slower-moving, security-patched, built for stability and long installs.
-
linux-hardened
Hardening patches on top of the kernel — hardened allocator, stronger exploit mitigations.
-
linux-cachyos
A performance-tuned kernel with scheduler and allocator tweaks; built for responsiveness.
-
linux-zen
Community kernel focused on desktop and multimedia performance — faster, more adventurous.
-
-
-
-
A choice, within a family
-
To be clear about the scope: the freedom here is within Linux — which Linux kernel, not whether to leave the family. Keru composes everything above the kernel however you like; the kernel itself has a well-tested set of variants to pick from. More on what Keru's freedom does and doesn't cover.
-
-
Baked in, not bolted on
-
Stage 2 of the build compiles the exact kernel you chose and wires your init to boot it. The kernel, the init, and everything else is one coherent profile — nothing prebaked, nothing to fight.
-
-
linux-lts for "set it and forget it," linux for the mainstream, hardened/zen/cachyos for the tradeoffs you actually want. Your call.
Every C program on your system links against a C library. It's the floor under userspace: malloc, printf, thread primitives, the syscall wrappers, all of it. Keru lets you choose which floor the rest of your system stands on.
-
-
-
-
glibc
The default, and the most compatible. Maximal feature set, broadest software support, the ecosystem baseline.
-
musl
Small, fast, clean implementation. MIT-licensed, statically-friendly, famous for strict correctness and small binaries.
-
uclibc-ng
The maintained fork of uClibc — designed for embedded and minimal systems, tiny footprint, configurable.
-
-
-
-
Why this is a choice
-
Binary distributions can't really offer this — a prebuilt package set is glued to one libc. A source-only distribution can, because it compiles everything against whatever you picked. Keru carries that through: your chosen libc is bootstrapped first (in the toolchain stage), and every package is built against it.
-
-
Stability notes
-
musl and uclibc-ng are early-0.1 territory. The installer's stability check currently flags uclibc-ng combinations as not-yet-proven, and musl + systemd as a known-hard pairing. Warnings — never blocks. The stance.
-
-
glibc is the default for a reason: it's the widest path. But "the path everyone takes" is an argument, not a law — and in Keru, you make the call.
Keru OS, kama, and kama-packages are licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). The full license text ships as LICENSE in each repository.
-
-
What that means, briefly
-
-
Freedom to use. Build, install, and run Keru on anything you like.
-
Freedom to study and modify. Source is available everywhere; it always has been — that's Keru's whole point.
-
Freedom to share. Redistribute copies (modified or not) under the same license.
-
Network use counts. If you modify Keru's software and offer it to users over a network, the AGPL requires you to offer the modified source — the "Affero" addition.
-
-
-
Derivative distributions welcome
-
Keru deliberately doesn't forbid forking or remixing. If another distribution wants to build on Keru — take the installer, the pipeline, the philosophy — it's welcome, under the AGPL. That's consistent with the ethos: the pieces are yours to assemble.
-
-
About this website
-
This site lives in web/ in the KeruOS repository, and is covered by the same AGPL-3.0. The design, copy, and markup are free to reuse under it.
-
-
License texts live in each repo root. The canonical document is the file, not this page.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/web/links.html b/web/links.html
deleted file mode 100644
index 68b1430..0000000
--- a/web/links.html
+++ /dev/null
@@ -1,62 +0,0 @@
-
-
-
-
-
-Links — Keru OS
-
-
-
-
-
-
-
-
-
-
live/init is the init for the Keru live ISO. Its entire job is to get you into the installer as fast as possible — no shell prompt, no manual steps between boot and "craft your system."
-
-
What it does, in order
-
-
Sets up the console. Redirects to $CONSOLE (/dev/tty1 by default) so installer messages land where you can see them.
-
Mounts virtual filesystems./proc, /sys, /dev (devtmpfs, with tmpfs fallback), /dev/pts, /dev/shm — the essentials the installer needs.
-
Locates the installer root. Uses the kernel's root= if given, or looks for a KERU*-labeled device to find the read-only squashfs payload; otherwise assumes the installer is on the current root.
-
Execs the installer.exec sh installer/install.sh — the TUI starts immediately.
-
Emergency shell fallback. If the installer exited or isn't found, you get an interactive rescue shell instead of a hang.
-
-
-
-
live/init
-
[ keru ] booting installer...
-[ keru ] Keru OS — craft your system
-== Init system == [runit]
-== C library == [glibc]
-== Filesystem == [ext4]
-# and you're choosing — the installer opened itself.
-
-
-
Design notes
-
-
Ultra-minimal. The live env is busybox + the installer. No init system in the live env — this script is the init.
-
Never strand you. The emergency shell is deliberate: "installer not found or exited" should never be a dead end.
-
Console-aware. It listens to the console= kernel param so serial consoles work too.
-
-
-
This is the "boot → choose → it builds" promise made real: the ISO carries the installer, and live/init hands it straight to you.
make.conf is the file the installer writes and Kama reads. Every swappable choice in Keru lives here — it's the record of your crafted system, and hand-tuning it then rebuilding is fully supported.
-
-
Profile — the swappables
-
# Which init system gets installed
-INIT=runit
-
-# Which libc the toolchain and packages build against
-LIBC=glibc
-
-# Which filesystem the target root is formatted as
-TARGET_FS=ext4
-
-# Which kernel you want built
-KERNEL=linux
-
-# Which privilege-elevation tool gets installed
-SUDO=doas
-
-# Base package set pulled into every install
-BASE_PACKAGES=(base toolchain openssh)
-
-# Locale / clock / keymap applied to the target
-LOCALE=en_US.UTF-8
-TIMEZONE=UTC
-KEYMAP=us
-
-
Build environment
-
# Compiler / linker flags passed to every recipe build
-CFLAGS="-O2 -march=x86-64"
-CXXFLAGS="$CFLAGS"
-LDFLAGS="-s"
-
-# Parallelism
-JOBS=$(nproc)
-MAKEFLAGS="-j$JOBS"
-
-# Mirror for source tarballs (unset: fetch straight from upstream)
-# SOURCE_MIRROR="https://mirror.example.org/sources"
-
-# Where the new target root lives on the build host
-ROOT=/tmp/keru/root
-
-# Persistent source + build cache (survives across installs)
-CACHEDIR=/var/cache/kama
-
-
Kama behaviour
-
# Remove temp build-time deps after use (AUR-style). Set to 0 to keep them.
-PURGE_TEMP_DEPS=1
-
-# Stop on first recipe failure
-FAIL_FAST=1
-
-
Why it's "the source of truth"
-
-
The installer writes it from your choices — every menu pick lands as a line here.
-
Kama reads it to know flags, mirrors, cache, and where to install into.
-
It's human-editable. The TUI is a convenience, not a gate. Edit, rebuild, repeat.
-
It's reproducible. The same make.conf should build the same system.
-
-
-
The canonical template lives in profile/make.conf at the repo root — the copy above mirrors it, but the repository file is the source of truth.
Every Keru build is a network operation. Package recipes always come from the GitHub-hosted kama-packages repo; this page is about the other half — the source tarballs each recipe downloads, and the cache they pass through.
-
-
Download order
-
-
1. SOURCE_MIRROR — tried first when set; run a mirror of source tarballs and point it here.
-
2. Upstream — the canonical source URL from the recipe. Used when no mirror is set or the mirror lacks a file.
-
Verification at every step. A file that doesn't match its checksum is dropped, and the next source in line is tried. Tampered files never reach a build.
-
-
-
The cache layout
-
/var/cache/kama/ # CACHEDIR (set CACHEDIR=/path to relocate)
-├── dl/ # downloaded tarballs, one per package
-├── src/ # extracted source (per package dir)
-└── stage/ # staged installs before they commit to $ROOT
-
-
-
Dir
Everything
Purpose
-
dl
Downloads
Already-downloaded archives are reused, never re-fetched.
-
src
Extracted
Extraction is skipped when the checked-out source is present.
-
stage
Staged builds
Progress survives a failed build; re-running continues.
-
-
-
Working offline, or your own mirror
-
# warm the cache once, then build with the network down
-SOURCE_MIRROR=https://mirror.example.org kama fetch busybox
-...
-CACHEDIR=/var/cache/kama kama make busybox # no network needed
-
Run a mirror yourself and point SOURCE_MIRROR at it. The layout mirrors dl/; the fetch layer treats it as a read-mostly source of truth.
-
-
Cleanup
-
-
rm -rf /var/cache/kama/src/* — free extracted source (re-extracts on next build).
-
rm -rf /var/cache/kama/dl/* — dump downloads (re-fetches next time).
A corrupt cache is the #1 source of confusing fetch errors. When in doubt, clear the relevant dir — downloads verify anyway, so you lose nothing but time.
scripts/mkfs-root.sh is the final stage of the build pipeline. Given your chosen TARGET_FS, it formats and assembles $ROOT so the disk reflects exactly the filesystem you selected at install.
-
-
What it does
-
-
Formats. Creates the filesystem image with the matching mkfs tool (ext4, btrfs, xfs, zfs, f2fs, jfs, reiserfs, swap, or the ext2/ext3 lineage).
-
Populates. Copies the built rootfs into the formatted volume.
-
Wiring. Ensures fstab and boot records match your selections.
-
-
-
Honest flags
-
The filesystem tooling is built in stage 2 from your choice — if you picked zfs, you get ZFS tools; if reiserfs, you get its (unmaintained) tooling, after a stability warning. Whatever you choose, the tooling and the format match.
-
-
The result of stage 3 is a rootfs that will boot — with the exact filesystem, kernel, init, and tools you picked. That's the whole pipeline in one line.
Connectivity is a hard requirement. The installer makes connecting easy.
-
-
-
-
-
-
Why networking is mandatory
-
The ISO carries only the installer — there's no prebuilt base image on the disk. Your entire system (toolchain, kernel, init, libc, filesystem tooling, tools) is fetched from the network and compiled during installation. So the installer treats a connection as a hard gate: no network, no install. It won't pretend otherwise.
-
-
The flow, exactly
-
-
Probe. The installer checks connectivity against several hosts (1.1.1.1, github.com) using ping, falling back to a TCP connect via nc if needed.
-
If connected: a simple [ keru ] network: connected and it moves straight to crafting your system.
-
If not connected: you're told, and asked — Connect to the network now (runs nmtui)? [Y/n].
-
Say yes:nmtui opens. Connect to your network, press okay.
-
Saying no: the installer exits with a network connection is required to install Keru.
-
Re-check. After nmtui closes, connectivity is probed again. If you're online, you continue. If not, it asks again — it never fakes success.
-
-
-
-
keru@live:~$
-
[ keru ] warning: network: not connected
-Connect to the network now (runs nmtui)? [Y/n] y
-(nmtui opens — pick your network, connect, press ok)
-[ keru ] network: connected
-
-
-
Details that matter
-
-
Wired is the path of least resistance. A physical Ethernet connection with DHCP typically just works — the probe succeeds and you skip straight to choosing.
-
Wireless goes through nmtui. The NetworkManager TUI handles Wi-Fi selection, WPA credentials, and the rest. The installer doesn't guess; it hands you the tool.
-
Loop, don't lie. If you run nmtui but never connect, the installer loops back to the prompt rather than proceeding on a "trust me, it worked" basis.
-
-
-
What if nmtui isn't available? The live ISO ships with it, so this is an edge case — but if it's missing, the installer tells you plainly and lets you bring the network up yourself before continuing.
The network stack has as many opinions attached as the init system. Keru applies the same rule: pick the manager you want, and it's built into your system — nothing wireless-by-default imposed, no "just use the standard one."
-
-
-
-
nmtui
The default. Just NetworkManager's terminal user interface — connect wires and Wi-Fi without a full manager on your system.
-
networkmanager
The full NetworkManager — daemon, D-Bus API, nmcli, handles wired, wireless, VPN, and more.
-
connman
Intel's connection manager — light, D-Bus bus–independent, designed for embedded and minimal systems.
The default is nmtui — the interface, not the daemon — which is the lean choice: you get the easy nmtui workflow during install without committing yourself to running NetworkManager's daemon afterward. If you want the full manager, it's one selection away.
-
-
Coherence
-
If you chose systemd as your init, systemd-networkd pairs naturally. If you're on runit or s6, a standalone manager (or just nmtui) fits the picture. The installer offers the pieces; you assemble them.
-
-
During install, network setup uses nmtui itself (the installer runs it when you need to connect) — independent of what you pick as your system's eventual network tool. The install-time network flow.
Keru (ける) is a Linux distribution built on a deliberately unusual premise: the distro holds no opinion about your system. Not a light opinion, not a sensible default disguised as neutrality — no position at all.
-
-
Most distributions are an answer to "who decides what your system is?" and the answer is usually "the maintainers, wisely." Keru's answer is different: you decide, at install time, and the distro builds exactly that.
-
-
What that means concretely
-
-
Init is a choice. runit, s6, openrc, systemd, busybox-init, sysvinit, dinit, shepherd — side by side, weightless.
-
Your C library is a choice. glibc, musl, uclibc-ng.
-
Your filesystem is a choice. ext4, btrfs, xfs, zfs, f2fs, jfs, reiserfs.
-
Your kernel is a choice. linux, linux-lts, hardened, cachyos, zen.
-
Even sudo is a choice. doas, sudo, opendoas, or su.
-
-
-
And it's source-only. The whole system — toolchain included — is compiled from original source by Kama, a package manager that's a ~225-line shell script. There are no binary packages, no opaque machinery, no background assumptions.
-
-
Why
-
Because "you get s6 and XFS whether you like it or not" is a fine stance for a distro that wants an opinion — but it's a burden for anyone who wants a system that is theirs. Keru's only opinion is that you have to form one. After that, it builds exactly what you chose.
Everything is at an early stage. The first installable release, 0.1, will ship as a bootable ISO. Until then: the design is public, the repos are live, and the road is documented.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/web/news/design-decisions.html b/web/news/design-decisions.html
deleted file mode 100644
index 09d518b..0000000
--- a/web/news/design-decisions.html
+++ /dev/null
@@ -1,58 +0,0 @@
-
-
-
-
-
-Design decisions, so far — Keru OS news
-
-
-
-
-
-
-
-
-
-
Keru is early enough that its choices are still choices, not habits — so we're recording the ones already made, and why. If a decision ever looks wrong, this is the record of what it was meant to do.
-
-
1. The package manager is a shell script
-
Kama (~225 lines, pure shell) reads make.conf and runs recipe commands. No resolver, no database, no binary format. Rationale: legibility over machinery. The real cost of a build is the compiler, not the manager, so the manager should be boringly simple.
-
-
2. Stability is warn-not-block
-
Keru guarantees stability on the combinations it offers, and warns (never stops) you past that. Rationale: stable-on-what's-offered keeps the promise honest, and never-lock-out keeps it faithful to the anti-opinionated ethos.
-
-
3. Three sibling repos
-
KeruOS, kama, kama-packages — separate, sibling by default, each human-sized. Rationale: independent cadence, legible diffs, clear ownership. Paths are overridable via KAMA_DIR/PKGS_DIR.
-
-
4. The ISO carries only the installer
-
No prebuilt base image on the disk. The entire system is fetched and compiled during install, with network as a hard gate. Rationale: this is what makes "everything is swappable" real rather than aspirational — power to choose comes from nothing being prebuilt.
-
-
5. All ephemeral build deps (AUR-style)
-
Build-time dependencies are compiled, installed, and purged after use (PURGE_TEMP_DEPS=1). Rationale: they never accumulate, so the final system reflects exactly what it needs to run — not what it needed to be built.
-
-
6. The installer auto-starts on boot
-
live/init execs install.sh directly; if it exits, an emergency shell catches you. Rationale: "boot → choose → build" should have zero friction, and a user should never be stranded.
-
-
7. The website lives in the OS repo
-
For now, the site ships inside KeruOS under web/ — plain static HTML, dark, no framework. Rationale: keep it close to the code it documents and framework-free to match the ethos; it can split out when it earns its own repo.
-
-
None of these are dogma — they're recorded because they're decisions, and decisions are meant to be repeatable or revisitble. This page is where revisiting starts.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/web/news/philosophy-is-architecture.html b/web/news/philosophy-is-architecture.html
deleted file mode 100644
index 877dc2d..0000000
--- a/web/news/philosophy-is-architecture.html
+++ /dev/null
@@ -1,53 +0,0 @@
-
-
-
-
-
-The philosophy is the architecture — Keru OS news
-
-
-
-
-
-
-
-
-
-
"You choose everything" sounds like marketing. It's not — it's the shape of the code. Keru's philosophy and its architecture are the same thing, and that's the whole stability argument in miniature.
-
-
The claim
-
Keru says every foundational component is a variable you resolve at install time. Here's how that's true at the structural level, not just in spirit:
-
-
-
The installer encodes the choices.install.sh presents switches and writes them into make.conf. Init, libc, fs, kernel, sudo, net — each a line.
-
The profile is the only interface.make.conf is what the build reads. There's no hidden stack to override your choices; the choices are the input.
-
Kama executes, doesn't decide. The package manager runs recipes. It has no opinion because it has no place for one.
-
The build is a pipeline of your selections. Stage 2 builds exactly $KERNEL, $INIT, $SUDO, $NET. Nothing else is possible.
-
-
-
Why that matters
-
A distro is stable-for-its-idea when saying the thing and doing the thing are the same act. There's no gap for the machine to betray the pitch. If the pitch says "whatever you chose lands on the disk," the pipeline is materially incapable of doing anything else — because its only inputs are your choices.
-
-
The boundary is honest too
-
The same architecture makes the limits visible. Choice multiplies combinations, so stability is scoped to what's offered, and risky picks get warned, not blocked — the warn-not-block stance. That's another place the philosophy and the structure agree: the installer tells you the truth because the design has no way to hide it.
The first installable release, 0.1, ships as a bootable ISO. No source builds for the user, no manual tooling — you boot it, the installer starts itself, you choose, and it builds. Here's the honest list of what has to be true before that ISO exists.
-
-
The pipeline must actually build
-
-
Toolchain bootstrap on real hardware. binutils → gcc → libc → toolchain, from literal nothing. This is the hard step; source distros live or die here.
-
A working base set.base, toolchain, openssh, and the tooling each swappable needs, all building against the chosen libc.
-
Every offered combo, proven. The stability promise is "stable on what we offer" — so the offering must be curated to what's tested.
-
-
-
The ISO must boot and install
-
-
live/init works. The ISO boots, mounts virtual filesystems, and hands you the installer with no prompt in the way.
-
Network gate works. Connectivity check, nmtui handoff, re-check loop — the hard requirement handled gracefully.
-
The installer writes a correct profile. Menus → make.conf → build, with the stability checks warning (never blocking) along the way.
-
The installed system boots. First boot runs the init you chose, on the filesystem you chose, with the kernel you chose. Fixed at first boot.
-
-
-
Honesty about the present
-
Right now the design is public, the repos are live, and this site documents it all — but nothing has booted on hardware yet. The gap between "the architecture is sound" and "0.1 exists" is exactly the work in this roadmap. We're not pretending it's done; we're saying plainly what remains.
-
-
When 0.1 lands, it will be linked here and on the install page. Until then, progress shows up in the news.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/web/philosophy.html b/web/philosophy.html
deleted file mode 100644
index 75948da..0000000
--- a/web/philosophy.html
+++ /dev/null
@@ -1,77 +0,0 @@
-
-
-
-
-
-Philosophy — Keru OS
-
-
-
-
-
-
-
-
-
-
Most distros ship a decision someone else already made for you — a default init, a default libc, a default filesystem. You inherit it and live with it. Keru refuses that premise. Every foundational component is a variable you resolve at install time, not a fixed value baked into the distribution. Every init, every libc, every filesystem, every kernel, every privilege-elevation tool — all selectable, none forced.
-
-
-
-
Anti-opinionated, not opinionated
-
Keru is not opinionated. It is anti-opinionated. An opinionated distro picks a stack and defends it — "you get s6 and XFS whether you like it or not." Keru is the direct rejection of that. It holds no opinion about which init, libc, filesystem, or daemon you should run, because that decision belongs to you, not to the distribution.
-
-
The distro's only opinion is that you have to form one. After that, it shuts up and builds exactly what you chose.
-
-
Only what you asked for
-
The install medium carries nothing but the installer. There is no prebuilt base image, no hidden bloat, no background assumptions. You pick your system, Keru fetches it and compiles it from source, and the disk reflects exactly that and nothing more. What gets built is defined by what you chose — not by what maintainers decided you should have.
-
-
Control without complexity
-
This is the deliberate bet, and the thing that separates Keru from a Gentoo skin. The package manager, Kama, is a shell script. It reads a make.conf and runs recipe commands. No dependency solver. No package database. No compiled manager machinery.
-
-
"Sure, the package manager is in shell, and that compromises performance — but it's still faster than many package managers people actually use, and the real cost of a build is the compiler, not the meta-machinery around it."
-
-
The dependency model is AUR-style ephemeral: build tools are fetched, compiled, and removed once they've served, so they never accumulate. The richness lives in the recipes and the profile, not in the machinery. Keru is the position that package managers became more complex than the packages they manage, and that the simple version is the right one.
-
-
"A package manager doesn't need a resolver to be honest. It needs to be legible — you can read every decision it makes, because every decision is a script or a line in make.conf you can see and change."
-
-
Squared with reality
-
Building every init, every libc, every filesystem from source at install time requires a working network connection, and the installer is honest about that: connectivity is a hard gate, and network setup happens inside the installer. This is what makes "everything is swappable" real rather than aspirational. The power to choose anything comes from the fact that nothing is prebuilt — you fetch exactly the parts you picked.
-
-
"You give up the convenience of a prebuilt system so the system you get is exactly the one you designed. Speed-to-install is traded for fit-to-request. If you want fast and prebaked, a binary distro is right there. If you want your machine, this is the one."
-
-
Stability, honestly scoped
-
Keru's promise is that the system won't break — on the combinations it offers you. That's a bounded promise, enforced by curation, and it never locks you out. You're warned, never blocked. Read the stability stance in full.
-
-
The through-line
-
Keru's lineage ran from TOML packages to a 50-line build DSL, then to plain shell. And from opinionated dogma — "you get s6 and XFS whether you like it or not" — to anti-opinionated anything-goes. Keru keeps the from-scratch purity while rejecting the fixed dogmas outright.
-
-
"We don't tell you which init to worship or which filesystem to trust. We tell you that you have to choose — and then we build exactly that."
-
-
The philosophy in one line:
-
A system should be exactly what you chose it to be — selected at install, built from source, nothing forced and nothing you didn't ask for.
No telemetry. Keru does not phone home — not during install, not at boot, not ever.
-
No accounts. There is nothing to sign up for to install or use Keru.
-
No tracking. No analytics SDKs, no crash reporters, no "improve your experience" data collection.
-
Nothing you didn't ask for. The only network activity comes from what you explicitly install, at install time, from the sources that package's recipe names.
-
-
-
This website
-
-
No cookies. No session tracking, no analytics scripts, no third-party trackers.
-
Static files only. Plain HTML/CSS/JS. The only external requests are the web fonts (from Google Fonts). If that matters to you, the site still works without them — it falls back to system fonts.
-
No accounts for content. Reading the site requires nothing.
-
-
-
About the download
-
When 0.1 ships as an ISO, downloading it is a plain file fetch from GitHub (a release asset). Nothing is recorded beyond what your server and service logs necessarily keep. If a mirror is ever added, this page will say so.
-
-
If that changes, this page changes first — and it will be public. Keru won't decide that telemetry is "fine actually" in a changelog.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/web/privilege-elevation.html b/web/privilege-elevation.html
deleted file mode 100644
index 86f21aa..0000000
--- a/web/privilege-elevation.html
+++ /dev/null
@@ -1,53 +0,0 @@
-
-
-
-
-
-Privilege elevation — Keru OS
-
-
-
-
-
-
-
-
-
-
Even "sudo" isn't sacred in Keru. How you elevate privileges is a swappable — the question of which su-style tool runs your privileged commands is settled by you, at install, alongside everything else.
-
-
-
-
doas
The default. OpenBSD's elegant, minimal replacement for sudo — small config, fewer lines, no surprise policies.
-
sudo
The familiar heavyweight. Fine-grained policies (sudoers), broad ecosystem familiarity.
-
opendoas
A portable, independently-maintained doas implementation for Linux — the doas philosophy with a maintained port.
-
su
The classic. No added abstraction — switch user and run what you need, as basic as it gets.
-
-
-
-
Why this is on the list
-
Privilege elevation touches everything an admin does, and it's usually a foregone conclusion: "you get sudo." Keru treats it as what it is — a tool with tradeoffs — and lets you pick the flavor. If you believe in two-line configs, doas. If you need sudoers granularity, sudo. If you want zero abstraction, su.
-
-
Whichever you choose gets built in stage 2 as part of your profile, alongside your kernel and init. Nothing preinstalled, nothing assumed.
-
-
Small opinion, stated plainly: doas is the default because two lines of config beats two hundred. But it's a default, not a dogma — swap it freely.
The contract between "what you chose" and "what gets built."
-
-
-
-
-
-
Keru's profile system is the hand-off between your decisions and the build. It's a small, open design:
-
-
The flow
-
-
You choose. The installer (installer/install.sh) walks each swappable and records your picks.
-
It writes a profile. Your choices become make.conf — plain, readable, human-editable.
-
The pipeline reads it.scripts/build-root.sh sources the profile and drives Kama with those exact settings.
-
The system appears. Kama boots the toolchain, builds the base, brings your chosen kernel/init/sudo/net, and finalizes the filesystem your profile named.
-
-
-
What the profile owns
-
-
Layer
What it holds
-
Swappables
INIT, LIBC, TARGET_FS, KERNEL, SUDO, NET.
-
Base set
BASE_PACKAGES — what every system gets (base toolchain openssh).
-
System config
LOCALE, TIMEZONE, KEYMAP.
-
Build env
CFLAGS, CXXFLAGS, LDFLAGS, JOBS, MAKEFLAGS.
-
Mirrors & cache
SOURCE_MIRROR, ROOT, CACHEDIR.
-
Kama behavior
PURGE_TEMP_DEPS, FAIL_FAST.
-
-
-
Hand-tuning is a feature
-
The installer is convenient, not precious. The profile it writes is just a text file — change INIT=s6, tweak CFLAGS, add a package to BASE_PACKAGES, and rebuild. The "craft your system" ethos extends past install into the profile itself.
-
-
The profile makes Keru reproducible and legible in one stroke: the same make.conf is the full description of the system. Read, edit, rebuild.
Every package in a Keru system is described by a recipe: a plain POSIX shell script in kama-packages. Writing one is closer to filling a form than engineering a build.
-
-
The template
-
kama-packages/TEMPLATE.sh is the canonical starting point. Copy it, fill the easy tier:
-
name=hello # required
-version=2.12.1 # required for fetch
-url=https://ftp.gnu.org/gnu/hello/hello-2.12.1.tar.gz
-deps=() # build-time deps, compiled then purged
-
-build() {
- ./configure --prefix=/usr
- make -j"$JOBS"
-}
-
-install() {
- make install DESTDIR="$pkgdir" # stage, never $ROOT
-}
-
-
A real, complete recipe
-
This is the entire busybox recipe currently in the repo:
-
name=busybox
-version=1.36.1
-url=https://busybox.net/downloads/busybox-1.36.1.tar.bz2
-deps=()
-
-build() {
- make defconfig
- make -j"$JOBS"
-}
-
-install() {
- make install CONFIG_PREFIX="$pkgdir"
-}
-
That's it. Kama downloads, extracts, strips the top dir, builds, stages, and installs.
-
-
Stepping up
-
-
Need
Field / function
-
Colliding with another package
provides=(...) conflicts=(...)
-
Build deps that must stay
runtime_deps=(...)
-
Arch-restricted
arch=(x86_64)
-
Repo or vcs sources
noextract=("$url") + own build()
-
Custom fetch (patch first)
pkg_fetch() { default_fetch; patch ...; }
-
Post-install work
pkg_post() · pkg_split() for subpackages
-
-
-
Rules of the road
-
-
Stage, don't touch.install() installs into $pkgdir. Kama commits the staging dir to $ROOT only after a successful build.
-
Add pure build deps to deps. They're purged automatically after the build (AUR-style). Keeps the door clean.
-
Declare the license.license=(SPDX) — supply chain cleanliness starts here.
-
Pin exactly. A fixed url + version, never a moving "latest".
-
-
-
Checking your work
-
sh -n recipe.sh # syntax check
-kama info <pkgname> # metadata parses (name from the recipe)
-make recipe-check # lint the whole kama-packages repo
-kama make <pkgname> # build it for real
-
-
The behavioral spec lives at recipe format. For hands-on, mirror the recipe concept page and start with busybox.sh, the smallest real recipe.
A recipe is a plain POSIX shell script describing how to compile and install one piece of software. The syntax splits into two tiers:
-
-
-
Easy — declare a few variables, fill in build and install, done. Covers ~90% of packages (autotools/cmake/meson).
-
Advanced — full control when you need it: custom fetch/extract, staging layout, packaging hooks, multi-arch, verification. Everything the easy tier does is sugar over this.
-
-
-
In both tiers, Kama sources the recipe and runs the functions you define.
-
-
-
-
Easy tier — most packages only need this
-
name=busybox
-version=1.36.1
-url=https://busybox.net/downloads/busybox-1.36.1.tar.bz2
-deps=() # build-time deps, purged after (AUR-style)
-
-build() { # configure + compile
- make defconfig
- make
-}
-
-install() { # install into $pkgdir (staging), not $ROOT
- make install CONFIG_PREFIX="$pkgdir"
-}
-
-
That's it. Kama supplies the conventional pkg_fetch (download + extract — auto-detects .tar.xz/.gz/.bz2/.zip, strips the top directory) and pkg_clean.
-
-
-
-
Advanced tier — override any step
-
name=busybox
-version=1.36.1
-url=https://busybox.net/downloads/busybox-1.36.1.tar.bz2
-deps=(gcc musl-headers) # temp build deps (AUR-style)
-runtime_deps=(musl) # stays installed
-license=(GPL-2.0)
-provides=(sh) # capability this package provides
-conflicts=(dash) # mutual exclusion
-arch=(x86_64) # if non-empty, restrict to archs
-noextract=() # URLs to download but NOT auto-extract
-
-# override auto extract (e.g. patching before configure)
-pkg_fetch() {
- default_fetch # run the easy-tier default
- cd "$src"
- patch -p1 < ../my.patch
-}
-
-build() { ./configure --prefix=/usr "$@" && make; }
-install() { make install DESTDIR="$pkgdir"; }
-
-
Fields
-
-
Field
Purpose
-
name
Package name. Required.
-
version
Release version. Required for fetch.
-
url
Upstream source (or list).
-
deps
Build-time dependencies — compiled, installed, then purged (AUR-style).
-
runtime_deps
Dependencies that stay installed.
-
license
SPDX license identifiers.
-
provides
Capabilities this package provides (virtuals).
-
conflicts
Mutual exclusions.
-
arch
Architecture allow-list; empty means any.
-
noextract
URLs downloaded but not auto-extracted.
-
-
-
Hooks and functions
-
-
Function
Role
-
build()
Configure + compile, run in the extracted source dir.
-
install()
Install into the staging dir ($pkgdir/DESTDIR), not the live root.
Keru's releases are honest about being releases: each one is a tested point in time of the three repos, assembled into an ISO that boots and installs without fanfare.
-
-
Versioning
-
keru-0.1.0.iso # {major}.{minor}.{patch}
-
-
Bump
When
-
major
The swappable set changes shape, or the philosophy moves — real milestones like the first ISO.
-
minor
New swappable or a new kama feature that stays backward-compatible.
-
patch
Recipe fixes, installer bugfixes, docs — anything that changes no contracts.
-
-
-
What the release ISO contains
-
-
The installer.installer/install.sh plus its payload.
-
The live init.live/init — boot the ISO, installer auto-runs.
-
The repos. kama and kama-packages pinned at the release commit. Everything else — every source tarball, every toolchain compile — is fetched and built at install time.
-
-
-
Release readiness
-
-
Check
What passes it
-
Combos boot
The proven set of the offered swappables all boot after install.
-
Installer clean
A full install from a cold boot, no keyboard runtime.
-
No blockers
Nothing warns-but-doesn't-block where it shouldn't; unproven combos warn loudly.
-
Docs match
make.conf, recipes, and this website agree with the shipped code.
-
-
-
Announcements
-
Releases are announced on the news page, with a changelog and the exact repos/commits the ISO was cut from. "0.1 when it's ready" — as tracked in the status above — remains the only roadmap.
-
-
Deliberately unglamorous. A release is a checkpoint the community can trust, not a marketing event. Read the news for the current one.
Keru's security stance follows from its design. No binaries, no opaque machinery, no hidden services. That shrinks the attack surface to things you can actually read.
-
-
Source-only by construction
-
There is no binary package store to compromise. Every package is compiled in your install from original source fetched over the network. The "prebuilt artifact" class of attack simply doesn't exist.
-
-
Verified fetch
-
-
Mirror then upstream. Downloads try SOURCE_MIRROR when set and fall back to upstream. Unset — the default — they go straight to upstream.
-
Integrity enforced. A fetched tarball that doesn't verify is refused, not untarred. Failed verification is a hard stop.
-
Pinned sources. Recipes pin the exact url and version. Nothing is ever pulled "latest" implicitly.
-
-
-
A toolchain you can audit
-
scripts/build-root.sh # ~shell; reads your make.conf
-profile/make.conf # your choices, explicit
-kama # ~225-line package manager
-kama-packages/*.sh # recipes as plain shell you can read top to bottom
-
The whole vertical slice from "make.conf" to "booted system" is a handful of shell files. That's the honest counter to the "trust the distro binary blob" model.
-
-
Privilege by your rules
-
Privilege elevation is swappable: doas (slender, auditable) is the default, with sudo, opendoas, and plain su available. Keru never preloads root-owned services or hidden daemons.
-
-
Kernel hardening, if you want it
-
Pick linux-hardened at install for a hardened kernel, or stick with stable linux. The choice is yours and applied at the moment your system is built.
-
-
Licensing, because supply chain is security
-
All three repos are AGPL-3.0. Recipes tag their license explicitly. Nothing in the pipeline is proprietary-black-boxed.
-
-
Trust is transitive: you still trust the sources you install and any mirror you point at. Keru's job is to make that trust chain visible and verifiable — not to pretend you can be protected from everything.
-
-
Reporting
-
Found a flaw in the installer, kama, or a recipe? File it with the stage and the failing artifact. See contact and troubleshooting.
Guaranteed on what's offered. Never enforced on you.
-
-
-
-
-
-
The promise, scoped
-
Keru's definition of stable is direct: the system won't break. But that promise is only honest if it's scoped. Keru guarantees it on the combinations it offers you.
-
-
That's what it means for the installer to offer a choice in the first place: each option in install.sh is one Keru has proven builds and boots. The offered set is curated so that it doesn't break. Choice multiplies the test surface — six inits, four libcs, seven filesystems, five kernels, and more produce well over a thousand possible systems. Guaranteeing every one of them is only honest if it's enforced by curation: Keru offers what works.
-
-
But you're never locked out
-
If you pick something that isn't yet proven — a libc and init never tested together, an unmaintained filesystem, an exotic kernel pair — Keru does not stop you. It warns you the combination is unstable and lets you proceed.
-
-
"Stability is a guarantee about what we offer, not a jail around the edge of it. If you want to push into the unproven, we tell you the truth and get out of your way."
-
-
The full definition, in one line:
-
-
The system won't break for any choice Keru offers you; for anything beyond that, Keru warns and steps aside — you stay in control, never blocked.
-
-
How the warning shows up
-
The installer runs a stability check after your selections. Known-risky combinations are flagged before anything is written:
-
WARNING
-uclibc-ng + runit: not yet proven to build and boot together
-musl + systemd: not yet proven to build and boot together
-this combination is unstable. Keru won't stop you — build at your own risk.
-
-
Some of the pairs Keru currently warns about:
-
-
Combination
Why it's flagged
-
uclibc-ng + anything
Pre-0.1, not yet proven to build and boot end to end.
-
musl + systemd
Systemd and musl are a known-hard pairing.
-
zfs as root fs
Needs kernel module + ZFS userspace; not yet proven.
-
reiserfs
Unmaintained; no stable future.
-
-
-
What stability means for choices that work
-
-
Reproducible. The same make.conf builds the same system.
-
Predictable. What you chose is what boots. No surprises smuggled in by defaults.
-
Kama never lies. The package manager's job is to do exactly what a recipe says — reliably, silently, and correctly.
-
-
-
The honest trade-off
-
"Extremely stable" and "everything is swappable" pull in opposite directions. Most famously-stable distros (Debian) gain stability by shrinking choice. Keru's stability therefore isn't "fewest things possible" — it's "whatever you chose, it builds and boots predictably, and Keru never hides a risk from you."
Every foundational component, yours to choose at install time.
-
-
-
-
-
-
Keru's differentiator is one sentence: nothing is fixed, nothing you didn't ask for is forced on you. The installer presents each foundational component as a flat, open choice, and the system that boots is assembled from exactly the ones you picked.
-
-
This is what distro arguments get settled with, resolved ahead of time by you instead of argued forever by maintainers. Runit vs systemd, glibc vs musl, ext4 vs btrfs, vanilla vs hardened kernel — all of it becomes your decision, made once, at install.
Kernel parameters, locale, clock, and keymap are all configurable too — surfaced through make.conf, the profile that your choices produce. The swappables aren't a fixed list; they're a stance. Read the make.conf reference.
-
-
Stability is scoped to these
-
Because choice multiplies the surface, Keru is stable on the combinations it offers, and warns (never blocks) beyond that. How that works.
-
-
-
-
-
-
-
-
-
-
-
\ No newline at end of file
diff --git a/web/toolchain.html b/web/toolchain.html
deleted file mode 100644
index a04248c..0000000
--- a/web/toolchain.html
+++ /dev/null
@@ -1,68 +0,0 @@
-
-
-
-
-
-Toolchain bootstrap — Keru OS
-
-
-
-
-
-
-
-
-
-
A source distro that seeds its compiler is a lie wearing a costume. Keru's stage 0 builds the toolchain from nothing — the assembler, the compiler, the C library, then a self-hosted toolchain package — before a single package in your system tree is compiled.
-
-
Why the order matters
-
-
Step
What runs
Why first
-
1
binutils
as, ld, ar — you can't compile without an assembler and linker.
-
2
a bare gcc
The C compiler, built against nothing but binutils.
-
3
your libc
glibc, musl, or uclibc-ng. Everything userspace depends on it.
-
4
a full gcc
Re-built now that the target libc exists (self-hosting).
-
5
toolchain package
Freezes the whole toolchain as a kama package for the rest of the build.
-
-
-
A bootstrap run
-
-
$ sh scripts/build-root.sh
-
[ keru ] stage 0: bootstrap toolchain
-[ keru ] binutils 2.42 ... ok
-[ keru ] gcc 13.2 (bare) ... ok
-[ keru ] glibc 2.39 ... ok
-[ keru ] gcc 13.2 (self) ... ok
-[ keru ] toolchain → ROOT ... ok
-[ keru ] stage 1: base system
-
-
-
Where it goes wrong
-
-
libc switch. Bootstrapping against musl or uclibc-ng rearranges the early stages; the exact package set lives with the libc page. A combo that isn't proven yet gets a warning — never a silent block.
-
Host leakage. Everything must link against the freshly built chain, not the build host's. The recipes pass explicit --host/--target and CC/CFLAGS so nothing sneaks in.
-
Double-build cost. gcc is compiled twice by design. That's the price of honesty; it's also a warm-up for the rest of the arch.
-
-
-
This is the line Keru draws: before your base system, a full self-hosting toolchain exists that didn't exist before. After that, the rest is just — as one long build script — more of the same.
Diagnose by stage. The stage points at the file to blame.
-
-
-
-
-
-
Almost every Keru failure lands in exactly one of five stages: live boot, network, fetch, build, or finalize. Figure out which, and you're most of the way to a fix.
-
-
Live boot
-
-
Symptom
Cause / fix
-
Drops to an emergency shell
live/init couldn't find the installer payload or mount buffers. Check the ISO layout and that you wrote the whole image, not just the files.
-
Installer never auto-starts
The live init runs installer/install.sh on boot. Run it by hand from the shell to see its errors directly.
-
Nothing on screen
Terminal TTY not your display? Verify the kernel picks your console; a plain getty on tty1 is the default.
-
-
-
Network
-
-
Installer says offline. It probes several hosts (1.1.1.1, github.com) and loops: it will offer to run nmtui, then re-check. Let it. GitHub reachability matters — package recipes are fetched from GitHub.
-
DHCP won't bite. Use nmtui and set a static address. The installer doesn't care how the link comes up, only that it does.
-
Slow fetch. When SOURCE_MIRROR is set it's tried first; upstream is the fallback. A broken mirror yields timeouts — fix or unset SOURCE_MIRROR.
-
-
-
Fetch
-
-
404 on a download. The recipe's url missed a version bump. Fix it or report it — sources are pinned in kama-packages.
-
Checksum mismatch. The tarball in the cache doesn't match the recipe. Clear the cache dir for that package: rm -rf /var/cache/kama/dl/<pkg>.
-
Mirror poison. If a third-party mirror serves a tampered file, fetch fails verification and refuses to proceed — by design.
-
-
-
Build
-
-
Symptom
Cause / fix
-
Compile error in a package
Often a C(FLAGS) interaction or a missing build dep. Add the dep and re-run kama make — stage dirs cache progress.
-
Missing header
That's a temp-dep gap in the recipe's deps=(). Contribute the fix: one line in kama-packages.
-
Toolchain failure
Stage 0 is the sharpest edge. A failing binutils/gcc/libc bootstrap is a bug — file it with the full make.conf combo.
-
Kernel build dies with no reason
Free disk or memory on the build host first; kernel builds are hungry. Then check KERNEL_CONFIG in make.conf.
-
-
-
Finalize and first boot
-
-
mkfs fails. The target device is in use or the filesystem tools for your pick are missing. Unmount and retry.
-
Won't boot. The init you chose must agree with how your bootloader was told to run it — check the boot command line and your init's expectations.
-
No network after boot. Your network tool choice (nmtui alone won't auto-connect) needs to be started on default runlevel or its service enabled.
-
Unstable combo. Keru warns on unproven pairs (musl+systemd, uclibc-ng, zfs root ...). Heed the warning or expect rough edges. It never blocks you.
-
-
-
When you file an issue, include the stage, your full make.conf combo, and the failing output. That's everything a maintainer needs. See contact.