- HTML 56.8%
- Python 32.8%
- QML 6.4%
- Shell 4%
| founding | ||
| mechanics/kadai | ||
| poc | ||
| seed/v4 | ||
| start | ||
| web | ||
| .gitignore | ||
| kadai-architecture.md | ||
| kadai-seed.md | ||
| kadai-sketch.md | ||
| kadai-subsidiarity.md | ||
| kadai-vision.md | ||
| LICENSE | ||
| me.example.md | ||
| README.md | ||
kadai
A small encrypted file holds what you told it about how you work, not who you are. From that file a personalised KDE Plasma desktop is compiled rather than installed, on every machine you admit, versioned and synced over git. The rules you write bind the code, and the code binds whatever makes suggestions: it proposes, you decide, nothing acts by itself.
The file is called me.md. It is encrypted at rest with age,
it lives in a git repository you own, and every machine you admit gets its own key
added to a recipient register. Next to it travel two KeePass databases: the keyring
with the accesses the system itself needs, which the machines can open, and the vault
with your own passwords, which only you open. No machine holds your passphrase. No
server holds any of it in the clear.
Where this lives
This repository lives on the project's own forge: https://git.relevantive.de/relevantive/kadai-playground (since 2026-10-04; before that on GitLab.com). Whether the project moves onto KDE infrastructure later is open; if it does, this file names the new address.
Status: this is a playground
Parts of this run today. Parts are a design on paper. The README says which is which because the difference matters.
Runs:
- Founding a system in the browser. A deterministic interview produces a valid kernel, encrypts it, and hands you a complete repository, pushed to GitLab or as a script for any git host. The accesses you type (storage, provider tokens) leave the page only encrypted, as the seed of your keyring. No model in that path, only a script.
- Admitting a machine, the guided way (
start/). On a machine that already runs Ubuntu: open an address, download one package, install it, and an assistant leads you to your desktop. It installs Plasma if it is missing, creates the machine's keys in the TPM where there is one, gives its sync key write access to your repository, takes your passphrase once, writes its key into the register and builds the desktop. First real run 2026-10-02 on an old Dell notebook. The seed image andbootstrap.shremain for an empty machine and for the terminal. - Retiring a machine is
.kadai-enroll.sh leaveon that machine, orrevoke <hostname>from any other: a revocation is an entry, and kernel and keyring password are re-encrypted without the key. - The keyring and the vault.
keyring.kdbxholds what the system needs (the storage login, provider tokens); its password is sealed to the register, so tools open it with the machine's key, through one script and never as a file.vault.kdbxholds your own passwords; only you open it, in KeePassXC. Both travel in the repository and merge per entry when two machines change them. - Reconciling the desktop. On every login a Python script drives a live Plasma session over D-Bus and brings it in line with the kernel's desktop spec. It is idempotent. Today the spec knows activities, their colour and panel widgets, so the desktop it builds is still a bare one.
- The sync. Local commit every ten minutes without touching the network, push on login, logout and hourly over a sync key that never asks for presence. Every failure lands in a log and a notification instead of disappearing.
- Where a model runs (
kadai-subsidiarity.md, prototype inpoc/rung/). Two ladders, capability and place; the smallest sufficient rung first, ascent only on measured failure, nothing leaves the machine to a provider without a preview and a yes. On the lab machine: a 0.8B model on the device, a 2B model on the network, a provider behind consent, driven from KRunner, shown in a panel at the right edge (the rail). - Two machines. When both change the kernel, the sync merges per entry: a change on one
side wins, the same change on both is fine, and different changes to the same entry
keep this machine's version and write a proposal with all three versions to
~/.config/kadai/proposals/. No timestamp decides, nothing is overwritten silently, and the repository is never left mid-merge. git cannot merge the ciphertext, so a merge driver,.kadai-merge.py, does it in plaintext on the machine.
Does not exist yet:
- The gate. The rules in
me.mdare English prose today. Nothing reads them and nothing enforces them. The design is written up inkadai-architecture.md: a deterministic policy compiled from structured blocks inside each rule, two enforcement points that together cover everything leaving the machine, and a refusal that turns into a proposal instead of a silent override. A model may draft a policy block, a human confirms it by committing it, and after that no model is ever in the path. - Observed data as a synced layer. The layering rule says observed data (what the
system notices, as opposed to what you told it) lives in append-only logs per machine
and merges by union. Today those logs exist per machine (
~/.config/kadai/*.tsv) and are not synced. - A richer desktop spec, the rail on every machine, a model on every machine. All three exist only on the lab machine, installed by hand.
- The portable person identity on hardware. Today the passphrase guards the master identity; a FIDO2 key is the planned next carrier, then a phone.
The demo under poc/demo-wizard/ shows the intended shape of the gate as an ordinary
program: before anything leaves the machine it shows you the exact payload, and the
model's answer is a proposal you can discard. It has no send command.
Try it
You already run Ubuntu. On a machine that already belongs, python3 start/kit.py go
builds a personal package and offers it on your network for twenty minutes. On the
new machine: open the address, download, double-click, start "Set up Kadai", log in
again, type your passphrase. Details in start/README.md.
You already run Linux with KDE Plasma and prefer the terminal. Any architecture:
KADAI_REPO=git@your-host:YOUR-NAME/kadai-kernel.git bash mechanics/kadai/bootstrap.sh
Run it without sudo. It needs git and age 1.3, creates the machine's keys,
installs the sync as a user service, and prints the deploy key you add to your
repository with write access. Then ./.kadai-enroll.sh join with your passphrase.
You want a whole desktop with nothing to set up. A generic Ubuntu plus Plasma image
that becomes yours only when you type your passphrase. The recipe is in seed/v4/,
built with mkosi. The built images are a few
gigabytes and are therefore not in this repository. Ask if you want one.
You have no system yet. Open web/gruendung/index.html in a browser, or the hosted
copy at https://kadai.relevantive.de, and answer the interview. At the end your
encrypted kernel sits in your own repository.
What is in here
| Path | What it is |
|---|---|
me.example.md |
An example kernel. Six sections, stable IDs, provenance per entry. |
mechanics/kadai/ |
What is installed into a kernel repository: sync, enrolment, keyring, storage, reconcile, bootstrap. |
founding/build.py |
Builds the founding page, embedding the mechanics above as text. |
start/ |
The guided way onto a machine that already runs Ubuntu: one package, one passphrase. |
seed/v4/ |
The mkosi recipe for the seed image. |
web/ |
The published site, German and English. |
poc/ |
The kernel parser, the consent demo, and under poc/rung/ the subsidiarity prototype: router, KRunner entrance, the rail. |
kadai-architecture.md |
The long form. Key architecture, protocols, threat model, the gate design. |
kadai-vision.md |
Why, rather than how. |
kadai-subsidiarity.md |
Where a model is used, who decides, how you see it. Concept, one page. |
kadai-seed.md |
How the seed image is built, including what went wrong. |
__KADAI_REPO__ in mechanics/kadai/bootstrap.sh and in the seed scripts is a
placeholder. The founding page substitutes your repository address when it hands you
the file. Running the script by hand, pass KADAI_REPO instead.
Things worth arguing about
- A recipient register is an OR. Every key in it opens the kernel completely. There is no 2-of-N, and pretending otherwise would be worse than saying so.
- Biometrics cannot be the portable root of an identity that has to move between machines, because the key never leaves the device that holds it. So there are two kinds of keys: machine keys that never leave their chip, and one person identity that you carry (today a passphrase, later a hardware key) and that alone may admit a machine.
- The keyring is as safe as the weakest machine in the register, because every machine can open it. That is why it holds only what the system needs, and your own passwords live in the vault that only you open.
- The desktop underneath keeps working if everything above it is removed. That is a design constraint, not an accident.
Licence
Code is GPL-3.0-or-later, see LICENSE. Documentation is CC-BY-4.0.
Contact
Jan Mühlig, muehlig@relevantive.de.