SmechOS Overview

SmechOS is an independent Linux distribution built entirely from source. It is not based on any existing distribution — no Gentoo, no Ubuntu, no Arch. The kernel, installer, package manager, and desktop are all maintained as first-party components.

Architecture

SmechOS is assembled by SmechDeploy (now spk-compile) — a pipeline of Python scripts that compile upstream sources and write the result into a bootable live ISO. This reflects the smechos-plasma-live build profile, the one currently shipping as SmechOS 1.0 Release Candidate 1.

Layer	Component	Notes
Desktop	KDE Plasma 6.6.6 (LTS)	KDE Frameworks 6.24.0, built from source via spk-compile -- pinned to the LTS line, not KDE's latest, see Source versions pinned
Display server	Wayland (KWin compositor)	Xwayland available for legacy X11 apps
Init system	systemd 261	Rebuilt from source with PAM support enabled
Login manager	PLM (Plasma Login Manager)	Autologin straight to desktop on the live ISO
Graphics	Mesa (compiled from source)	AMD RDNA/GCN, Intel (incl. Gemini Lake), virtio-gpu; full upstream linux-firmware cloned from git.kernel.org, not just GPU families
Toolkit	Qt 6.10.3	Built from source with fontconfig + XCB support
Kernel	Linux 6.12.16	Compiled as part of the spk-compile pipeline
Bootloader	GRUB 2.12	EFI + BIOS hybrid, El Torito live boot
Package manager	spk v2.5	Rust binary, unified install/remove/upgrade/deploy, plus `compile` (build one package) and `build-image` (build a whole OS image)
App store frontend	Plasma Discover	Backed by PackageKit → spk packagekit-backend
Installer	Calamares	Graphical installer, optional -- boots straight to a live desktop either way

Note SmechOS does not use Portage, APT, DNF, or any other external package manager. spk fetches packages from configured repos (or a local file) and extracts them directly -- no emerge, no apt, no flatpak. As of spk v2.2.0+, packages are real .spkg archives (deb-style: a control metadata file plus a payload, see spk Package Manager below) with a real installed-package database and name-based dependency resolution -- spk remove checks reverse dependencies and never deletes a file another installed package still owns. The older bare .tar.xz bundle format is still supported as a fallback for repos that haven't migrated.

Installing (Live ISO)

SmechOS ships as a live ISO. Boot it and you're straight into a working KDE Plasma desktop -- no install step required. Calamares is available on the live desktop if you want to commit the install to disk.

Requirements

x86_64 CPU with SSE4.2
4 GB RAM minimum (8 GB recommended for KDE Plasma)
40 GB disk space minimum (only if installing to disk via Calamares)
UEFI or BIOS boot

Steps

Download the ISO from os.smech.xyz/downloads and verify its checksum.

Write to USB:

sudo dd if=SmechOS-1.0-RC1.iso of=/dev/sdX bs=4M status=progress && sync

Boot the target machine from the USB. Autologin takes you straight to the KDE Plasma desktop.
Optional: run Calamares from the desktop to install to disk.

Warning This is a Release Candidate, not a stable release. The core boot path (live desktop, autologin, GPU rendering) is verified on real hardware, but it hasn't had a broad hardware compatibility pass yet.

netinst Installer (EoL)

End of Life The network installer described below is no longer maintained or recommended -- use the live ISO above instead. Kept here for reference since the underlying smechos build profile (musl + OpenRC, distinct from the live ISO's systemd + glibc profile) may be revisited in the future.

SmechOS previously shipped as a network installer ISO (netinst), built from a separate musl + OpenRC profile. The installer downloaded packages from the internet during installation and required a wired Ethernet connection.

Requirements (netinst, EoL)

x86_64 CPU with SSE4.2
4 GB RAM minimum (8 GB recommended for KDE Plasma)
40 GB disk space minimum
UEFI or BIOS boot
Wired Ethernet for the installer

Steps (netinst, EoL)

Write to USB:

sudo dd if=smechos-installer-minimal-netinst.iso of=/dev/sdX bs=4M status=progress && sync

Boot the target machine from the USB. The installer launches automatically.
Follow the TUI wizard: language → country → timezone → hardware detection → network → partitioning → base install → profile → GRUB → done.
Remove the USB and reboot.

spk — SmechOS Package Manager

spk (Smech Sovereign Package Keeper) is a zero-dependency Rust binary that manages packages on any Smech Labs OS. It does not call emerge, apt, flatpak, or any other external package manager -- it shells out to curl/tar/sudo for everything external instead of linking archive/HTTP crates. Plasma Discover and other PackageKit-aware frontends can install packages through SPK via the built-in PackageKit script backend.

Download

File	Version	Platform
spk	v2.5.0	x86_64 Linux

# Install to /usr/local/bin
curl -fsSL https://github.com/Smech-Labs/spk/releases/download/v2.5.0/spk -o spk
chmod +x spk
sudo mv spk /usr/local/bin/spk

Full release notes and source: github.com/Smech-Labs/spk/releases/tag/v2.5.0

Commands

spk install <package>

Fetches <package>.spkg (falling back to the legacy <package>.tar.xz) from each configured repo in priority order and extracts it into the root filesystem, resolving and installing any depends: first. When run on the build host with /mnt/smechos mounted, it targets that mount instead of /. Replaces the old system-install and userland-install split — all packages are now installed with one unified command.

spk install kernel-modules
spk install plasma
spk install plasma-discover

spk install --local-package <path>

The only sanctioned way to install a .spkg file already on disk. A bare path passed to install (spk install ./foo.spkg) is rejected on purpose, pointing you at this flag instead -- so where a package came from is always explicit.

spk install --local-package ./kcoreaddons-6.24.0.spkg

spk local-package-repo <folder>

Registers a local directory of .spkg files as a repo source (priority 1, checked first) -- writes a file:// entry into /etc/spk-repo-conf.yaml.

spk local-package-repo /mnt/smechos-packages-spkg

spk remove <package> [-y] [--force]

Uninstalls a package. Refuses if another installed package still depends on it (--force overrides), and never deletes a file another installed package also owns.

spk remove kquickimageeditor

spk list / spk depends <package>

list shows every installed package; depends prints a package's full dependency tree from the installed-package database at /var/lib/spk/installed/.

spk create-live-image <out.iso> [extra-pkg...]

Builds a bootable image straight from a repo's already-published .spkg packages, via an index.txt the repo publishes alongside them -- no compiler, no spk-compile.py, no source tree. Falls back to squashfs-only, honestly, if the package set doesn't include a kernel + initrd.

spk compile <recipe> [-o out.spkg]

Builds ONE package's source into a .spkg -- pure Rust, no spk-compile.py involved. A recipe is a control-style header followed by #--build--/#--install-- shell script blocks. Not to be confused with spk build-image below, which builds an entire OS image from source.

spk system-upgrade

Re-fetches and reinstalls every known package from the release. On SmechVisor, performs a live OTA upgrade: the daemon binary is hot-swapped without a reboot; base system components flag for reboot separately.

spk system-upgrade

spk build-image <profile> [options]

Native build orchestration — delegates to spk-compile.py (Project SmechDeployV2). Builds a full OS from source. (Named spk compile before v2.5.0 — that name now means "build one package's source into a .spkg" instead, see spk-compile documentation.)

spk build-image smechos-plasma-live              # full SmechOS live ISO build
spk build-image smechvisor                       # full SmechVisor build
spk build-image smechos-plasma-live --phase kde  # run one phase only
spk build-image iso smechvisor                   # build install ISO
spk build-image iso shim                         # build deploy shim ISO
spk build-image --list smechos-plasma-live       # list all phases

spk deploy-system-img-copy <code>

Pushes SmechVisor packages to a target node running the Deploy Shim ISO. Discovers the shim via UDP broadcast and streams packages over TCP. Run this on the donor SmechVisor node.

spk deploy-system-img-copy a1b2c3d

spk receive-deploy

Runs on the target node (normally started automatically by the shim). Generates a 7-character code, broadcasts it via UDP every 2 seconds, and opens a TCP listener for the donor to stream packages into /mnt/target. Reboots when transfer completes.

spk about

Displays SPK version, license (MIT), homepage, source repo, and developer credits (Smech Labs, lead developer, co-developers).

spk version

Prints the SPK version string. Current release: 2.5.0.

PackageKit integration (Plasma Discover)

SPK ships a PackageKit script backend at /usr/lib/packagekit-backend/pk-backend-spk.py. PackageKit calls this backend, which forwards the protocol to spk packagekit-backend. This means Plasma Discover — and any other PackageKit-aware frontend — can browse, install, and update SmechOS packages graphically without touching the terminal.

The Plasma Discover and PackageKit binaries are built by bin/compile_plasma_discover.sh and included in the SmechOS image via the discover phase in spk-compile.py.

Known packages

Category-level bundles are being replaced by individual per-component .spkg packages -- every Qt6 module (qtbase, qtdeclarative, qtwayland, qtmultimedia…) and every KDE Frameworks/Plasma component (kcoreaddons, plasma-desktop, kwin…) now builds and packages independently, generated by spk-compile's bundle-spkg phase. The table below is the older category-level scheme, still used as a fallback for anything not yet atomized:

Package	Contents
`base-system`	GNU userland compiled against glibc (coreutils, bash, tar, gzip, xz…)
`kernel-modules`	Linux 6.12.16 kernel modules
`firmware`	Full upstream linux-firmware, not just GPU families
`bootloader-grub`	GRUB 2.12 EFI + BIOS binaries, built from source
`kde-frameworks`	KDE Frameworks 6.24.0 libraries (legacy bundle; see per-component `.spkg`s above)
`plasma`	KDE Plasma 6.6.6 LTS desktop (legacy bundle; see per-component `.spkg`s above)
`qt6`	Qt 6.10.3 runtime libraries (legacy bundle; see per-module `.spkg`s above)
`mesa-graphics`	Mesa OpenGL/Vulkan stack
`plasma-discover`	Plasma Discover GUI package manager
`packagekit-spk`	PackageKit daemon + SPK backend

Legacy aliases The old system-install, userland-install, and entire-system-upgrade commands still work in SPK v2 — they print a deprecation notice and forward to the new command. Update any scripts to use the new names.

Building from Source

SmechOS is built entirely by spk-compile — a single standalone Python 3 script with no external dependencies.

# Get spk-compile
curl -fsSL https://github.com/Smech-Labs/spk-compile/releases/download/v2.2.0/spk-compile.py -o spk-compile.py

# Full SmechOS live ISO build (requires root for make install steps)
sudo python3 spk-compile.py smechos-plasma-live

# Or via spk (spk build-image since v2.5.0 -- see spk's README)
spk build-image smechos-plasma-live

See the spk-compile documentation for the full phase reference. Phase 1 operates directly on images/part2.img via debugfs without mounting. Phase 2 compiles sources from essentials/ into /mnt/smechos.