KAMOS — Gaming Linux OS

KAMOS is a custom Linux gaming operating system for PCs and laptops, built on top of Bazzite's stable channel (Fedora Atomic). It is an image-based OS: the whole system ships as one tested image, updates are atomic, and you can roll back from the boot menu if an update ever misbehaves.

Everything Bazzite ships is included out of the box: Steam with Proton, Gamescope, MangoHud, GameMode, HDR/VRR support, the fsync gaming kernel, KDE Plasma, Distrobox, and Waydroid.

KAMOS is built and hosted entirely on your own Forgejo instance — Forgejo Actions builds the images, and Forgejo's container/package registry serves them. The build runner is deployed as a Coolify service (your existing Forgejo is not modified in any way).

Variants

Image	For
kamos	AMD and Intel graphics (uses built-in Mesa drivers)
kamos-nvidia	NVIDIA graphics (proprietary driver pre-installed)

Both work on desktops and laptops. For laptops with hybrid AMD+NVIDIA or Intel+NVIDIA graphics, use kamos-nvidia.

One-time setup

Server needs ~40 GB free disk and 4+ GB RAM. Coolify's job here is only to run the build runner container — the runner connects to Forgejo with a token; your existing Forgejo service is untouched.

1. Get a runner registration token from Forgejo

Forgejo → Site administration → Actions → Runners → Create new runner → copy the registration token. (This only creates a token; it changes nothing.)

2. Deploy the runner in Coolify

Coolify → your project → New Resource → search git → select Gitea Runner (Forgejo's Actions runner is compatible with Gitea's — there is no separate Forgejo Runner template). Before deploying, set the environment variables:

Variable	Value
GITEA_INSTANCE_URL	https://YOUR-FORGEJO-DOMAIN
GITEA_RUNNER_REGISTRATION_TOKEN	the token from step 1
GITEA_RUNNER_NAME	kamos-builder
GITEA_RUNNER_LABELS	ubuntu-latest:docker://ghcr.io/catthehacker/ubuntu:act-22.04

(GITEA_TOKEN can stay empty — it's an alternative to the registration token.)

Then, still in the service before/after first deploy:

1. Storages → Add File Mount: destination /config.yaml, content = the file coolify/runner-config.yaml from this repo. This lets build jobs use the host Docker daemon (required).
2. Add env var CONFIG_FILE=/config.yaml.
3. Deploy. In Forgejo → Site administration → Runners, kamos-builder should appear as online with the ubuntu-latest label.

3. Configure the repo

1. Create a repository named kamos on your Forgejo and push this folder to it (make sure Repository → Settings → Actions is enabled).
2. In both workflow files under .forgejo/workflows/, change REGISTRY_HOST: git.example.com to your Forgejo domain.
3. In Forgejo: your avatar → Settings → Applications → Generate new token with package read/write scope. Then in the repo: Settings → Actions → Secrets, add:
   • REGISTRY_USER — your Forgejo username
   • REGISTRY_TOKEN — the token you just generated
4. Push to main — the Build KAMOS images workflow builds both variants (30–60 min first run; the ~8 GB Bazzite base download is cached after that).
5. After the first build: profile → Packages → kamos and kamos-nvidia → package settings → visibility Public (so installed machines and the ISO builder can pull without credentials).

4. Build an installer ISO

Repo → Actions → Build KAMOS installer ISO → Run workflow → pick kamos or kamos-nvidia. The finished ISO is uploaded to your Forgejo package registry under kamos-iso — download it from your profile's Packages page.

The weekly scheduled rebuild keeps KAMOS current with upstream Bazzite stable and Fedora security updates; installed machines pick these up automatically.

Installing

Fresh install: write the ISO to a 16 GB+ USB stick with Fedora Media Writer or Rufus (DD mode), boot from it, and follow the installer.

Already running Bazzite / Fedora Atomic? Rebase without reinstalling:

rpm-ostree rebase ostree-unverified-registry:YOUR-FORGEJO-DOMAIN/YOUR-USERNAME/kamos:stable

(use kamos-nvidia:stable for NVIDIA), then reboot.

Secure Boot: Bazzite's kernel is signed with Universal Blue's key. Either disable Secure Boot in the BIOS, or enroll the key as described in the Bazzite docs.

Customizing KAMOS

• Add/remove system packages: edit build_files/packages.list — one package name per line, # for comments. Push, CI rebuilds.
• Add/remove default apps (Flatpaks): edit system_files/usr/share/kamos/flatpaks.list with Flathub app IDs — installed automatically on each machine's first boot.
• Wallpaper/logo: replace system_files/usr/share/backgrounds/kamos/kamos-default.png and system_files/usr/share/pixmaps/kamos-logo.png. The build stamps the wallpaper over all stock desktop wallpapers.
• Add config files: drop them under system_files/ mirroring the target path (e.g. system_files/etc/foo.conf → /etc/foo.conf).
• Apps like Heroic, Lutris, Discord, OBS: install as Flatpaks after boot (Discover app store) — that's the intended pattern on image-based systems.
• Download page: if you want a public KAMOS website with download links, deploy a small static site with Coolify pointing at the ISO URLs in your Forgejo package registry.

Building locally (optional)

Requires Linux or WSL2 with podman or docker:

docker build --build-arg BASE_IMAGE=ghcr.io/ublue-os/bazzite --build-arg BASE_TAG=stable -t kamos:stable .

Layout

Containerfile              OS image recipe (FROM bazzite:stable)
build_files/build.sh       packages + branding applied at build time
system_files/              files overlaid onto the OS (/etc, /usr, ...)
disk_config/iso.toml       installer ISO configuration (optional kickstart)
coolify/runner-config.yaml runner config for the Coolify Gitea Runner service
.forgejo/workflows/        CI: image build + ISO build (Forgejo Actions)