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.7.2	KDE Frameworks 6.27.0, built from source via spk-compile
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; amdgpu/i915 firmware bundled
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	Rust binary, unified install/upgrade/compile/deploy
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 downloads pre-built tarballs from GitHub Releases and extracts them directly. There is no package database or dependency resolver — packages are designed to be self-contained.

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 v2.0 (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. Every package is a .tar.xz archive fetched from the Smech Labs package repository via curl and extracted with tar. 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.0.1	x86_64 Linux

# Install to /usr/local/bin
curl -fsSL https://github.com/Smech-Labs/spk/releases/download/v2.0.1/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.0.1

Commands

spk install <package>

Fetches and extracts a package into the root filesystem. 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 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 compile <profile> [options]

Native build orchestration — delegates to spk-compile.py (Project SmechDeployV2). Builds a full OS from source.

spk compile smechos-plasma-live              # full SmechOS live ISO build
spk compile smechvisor                       # full SmechVisor build
spk compile smechos-plasma-live --phase kde  # run one phase only
spk compile iso smechvisor                   # build install ISO
spk compile iso shim                         # build deploy shim ISO
spk compile --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.0.1.

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

Package	Contents
`base-system`	GNU userland compiled against glibc (coreutils, bash, tar, gzip, xz…)
`kernel-modules`	Linux 6.12.16 kernel modules
`firmware`	CPU microcode, amdgpu/i915 GPU firmware blobs
`bootloader-grub`	GRUB 2.12 EFI + BIOS binaries
`kde-frameworks`	KDE Frameworks 6.27.0 libraries
`plasma`	KDE Plasma 6.7.2 desktop
`qt6`	Qt 6 runtime libraries
`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 compile 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.