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 — a pipeline of shell and Python scripts that compile upstream sources and write the result into raw disk images.

Layer	Component	Notes
Desktop	KDE Plasma 6.6.5	Built from source via SmechDeploy
Display server	Wayland (KWin compositor)	X11/XWayland available for legacy apps
Init system	OpenRC	No systemd — plain shell service scripts
Graphics	Mesa (compiled from source)	AMD RDNA / Intel / virtio-gpu
Toolkit	Qt 6	Built from source, no distro packages
Kernel	Linux 6.12.16	Compiled by `compile_kernel.sh`
Bootloader	GRUB 2.12	EFI + BIOS hybrid
Package manager	spk v2	Rust binary, unified install/upgrade/compile/deploy
App store frontend	Plasma Discover	Backed by PackageKit → spk packagekit-backend
Installer	smech-installer	Rust + Newt TUI, netinst

Note SmechOS does not use Portage, APT, DNF, or any other external package manager. spk downloads pre-built tarballs from the SmechDeploy GitHub Release and extracts them directly. There is no package database or dependency resolver — packages are designed to be self-contained.

Installing

SmechOS ships as a network installer ISO (netinst). The installer downloads packages from the internet during installation — you need a wired Ethernet connection for the install process.

Requirements

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

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

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. SmechOS boots into KDE Plasma.

Warning This is an early beta release. The installer boots and walks through all wizard steps but has not been verified for a complete end-to-end install on all real hardware configurations. Treat it as a preview.

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              # full SmechOS build
spk compile smechvisor           # full SmechVisor build
spk compile smechos --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       # 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 musl (coreutils, bash, tar, gzip, xz…)
`kernel-modules`	Linux 6.12.16 kernel modules
`firmware`	CPU microcode, GPU firmware blobs
`bootloader-grub`	GRUB 2.12 EFI + BIOS binaries
`kde-frameworks`	KDE Frameworks 6 libraries
`plasma`	KDE Plasma 6.6.5 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 build (requires root for make install steps)
sudo python3 spk-compile.py smechos

# Or via spk
spk compile smechos

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.