Shanios Docs

Comprehensive technical documentation for Shanios — the immutable Linux OS.

Architecture

• Boot Process — Shanios uses a fully measured, signed boot chain built on systemd-boot, dracut-generated Unified Kernel Images (UKIs), and optionally TPM2 +
• Btrfs Deep Dive — Shanios leverages advanced Btrfs features for immutability, efficiency, and data integrity. Copy-on-Write (CoW) Btrfs CoW minimises storage
• Build Pipeline — Shanios images are produced by a multi-stage build pipeline that takes a package list, an overlay filesystem, and a profile-specific customi
• Dracut Initramfs Module — Shanios ships a custom dracut module (99shanios) that adds three hooks to the initramfs. These hooks implement the two features that require
• Filesystem Structure — Shanios uses Btrfs with a sophisticated subvolume layout housed in a single Btrfs partition (plus a 1 GB FAT32 ESP). The design separates th
• Overlay Filesystem — Shanios uses Linux OverlayFS to present a fully writable /etc on top of a read-only root filesystem. This is what makes the immutable OS fee

Concepts

• Atomic Updates — Shanios uses an intelligent multi-layered update system with automatic checking, user notifications, and the shani-deploy tool for atomic sy
• Blue-Green Deployment — Shanios implements blue-green deployment using Btrfs subvolumes — a strategy adapted from DevOps for desktop Linux. How It Works 1. System m
• Immutability — Shanios's immutability fundamentally changes how you interact with the system. Understanding this concept is key to using Shanios effectivel
• Persistence Strategy — Shanios selectively persists data across immutable system updates through bind mounts and dedicated Btrfs subvolumes. Three Categories ❌ Rep

Enterprise

• Cloud Images Beyond AWS — What exists today for non-AWS targets, what you can build yourself, and how far official support extends. Current Reality There are two dist
• Compliance & Benchmarks — How Shanios maps to common audit frameworks, what is satisfied by construction versus what remains an administrative action, and how to gene
• Fleet Monitoring Runbook — Shanios ships no fleet dashboard by design — no central console, no MDM server, no agent phoning home. Observability is composed from standa
• OEM & Fleet Deployment — Shanios is designed for fleet-scale management. Every machine pulls from the same GPG-verified image. Updates are atomic and all-or-nothing.

FAQ

• FAQ — Answers to the most common questions about Shanios — software installation, updates, hardware, security, and the immutable architecture in p

Installation

• First Boot — Plymouth BGRT Boot Theme Shanios uses the Plymouth BGRT boot theme. Plymouth provides a smooth graphical boot experience, suppressing kernel
• Pre-Installation Setup — BIOS/UEFI Configuration Configure your firmware before installation (typically accessed via F2, F10, Del, or Esc during startup): 1. Enable
• System Requirements — Hardware Requirements | Component | Minimum | Recommended | |-----------|---------|-------------| | Processor | x8664 dual-core with VT-x/AM
• Installation Steps — Installation takes approximately 10–15 minutes. Step-by-Step 1. Boot from USB — Press F12, F2, or Del during startup. Select your USB drive

Introduction

• How Shanios Compares — Immutable, atomic-update Linux distributions share one idea: the running system is never modified in place. Updates land as a complete, veri
• Getting Started — A complete walkthrough: choose your edition, download and verify the ISO, install, and configure Shanios for daily use. Choosing Your Editio
• Migrating from Traditional Linux — If you're coming from Ubuntu, Fedora, Arch, or any mutable Linux distro, the main adjustment is how you install software and make system-lev
• System Optimizations — Shanios includes extensive performance, gaming, and reliability optimizations out of the box, eliminating the need for manual tweaking. Thes
• Switching from Windows & macOS — This guide is for anyone leaving Windows or macOS for Shanios — whether you are migrating one laptop, setting up a family machine, or moving
• User Configuration — The primary user is automatically configured with appropriate permissions during installation. Shanios also watches for newly created users:
• What is Shanios? — Shanios is an immutable Linux distribution that brings enterprise DevOps practices to desktop computing. Built on Arch Linux with Btrfs file
• What's Included — Shanios comes fully equipped with a comprehensive software stack, carefully curated for desktop computing, development, gaming, and professi

Networking

• Apache HTTP Server — Apache is a full-featured, battle-tested web server. On Shani OS, Caddy is the recommended reverse proxy for self-hosted services due to its
• apcupsd (UPS Daemon) — apcupsd monitors APC Uninterruptible Power Supplies and triggers a graceful system shutdown when battery runs low. It is pre-installed on Sh
• arpwatch (ARP Monitor) — arpwatch monitors Ethernet ARP traffic and maintains a database of IP-to-MAC address mappings. It sends an email alert (via the local MTA) w
• Avahi (mDNS) — Avahi is active by default — your machine is immediately reachable as hostname.local on the LAN. It is used by CUPS (printers), KDE Connect,
• BIND (Authoritative DNS) — BIND (named) is the most widely deployed DNS server. On Shani OS it is pre-installed and provides two distinct functions that are often comb
• Bluetooth — Shanios pre-installs the full BlueZ stack (shani-bluetooth) and enables the Bluetooth daemon by default on every edition — pairing works out
• Caddy — Caddy is a modern web server with automatic HTTPS. It provisions and renews TLS certificates entirely automatically — via Let's Encrypt for
• Cloudflared Tunnels — Cloudflared creates an encrypted, outbound-only tunnel from your Shani OS machine to Cloudflare's global edge network. This lets you expose
• dnscrypt-proxy (Encrypted DNS) — dnscrypt-proxy encrypts DNS queries between your machine and upstream resolvers using DNSCrypt or DNS-over-HTTPS (DoH). Without it, DNS quer
• dnsmasq (Local DNS) — dnsmasq is a lightweight DNS forwarder, local caching resolver, and DHCP server — ideal for homelab setups. Use it for custom .home domains,
• Exim (Mail Transfer Agent) — Exim is a pre-installed Mail Transfer Agent (MTA). On a desktop or homelab machine, its primary purpose is local mail delivery — routing sys
• Fail2ban (Brute-Force Protection) — fail2ban monitors log files for repeated authentication failures and temporarily bans offending IPs via firewalld. It integrates with firewa
• Firewall (firewalld) — firewalld is active by default on Shani OS with a restrictive inbound policy. It manages nftables under the hood using a zone-based model —
• gpsd (GPS Daemon) — gpsd is a service daemon that reads data from GPS/GNSS receivers and makes it available to multiple clients over a local socket. Application
• How Container Networking Works — How Container Networking Works Understanding what Podman does under the hood helps debug connectivity issues between containers and the host
• IP Addressing & Routing — This page covers IP addressing fundamentals — CIDR notation, subnetting, IPv4 and IPv6 — and practical ip command usage for managing address
• iptables and nftables Basics — iptables and nftables Basics Firewalld (used throughout this wiki) is a high-level interface over nftables on modern Linux. Understanding th
• KDE Connect — KDE Connect integrates your phone (Android/iOS) with your Shani OS desktop over the local network. It's pre-installed on the KDE Plasma edit
• Kerberos — Kerberos provides strong mutual authentication for client/server applications using secret-key cryptography. It is the standard for enterpri
• ModemManager (Mobile Broadband) — ModemManager is pre-installed on Shani OS and integrates with NetworkManager to provide first-class support for USB and PCIe mobile broadban
• nbd-server (Network Block Device) — NBD exports a block device (disk, partition, or image file) over the network. The client side presents it as a local block device (e.g., /de
• Network Debugging Quick Reference — Network Debugging Quick Reference These commands are the foundation of diagnosing connectivity, DNS, and firewall problems on any Linux host
• Network Tools — Shanios includes a comprehensive suite of networking utilities for diagnostics, monitoring, security, and file transfer. All tools listed he
• NetworkManager & VPN — NetworkManager is pre-installed and active by default on Shani OS. It manages all network connections — wired, Wi-Fi, mobile broadband, and
• NFS File Sharing — Native Linux file sharing at near-local disk speeds. Best for Linux-to-Linux sharing on a trusted LAN. NFS state is bind-mounted from /data/
• openresolv (DNS) — Shani OS uses openresolv to manage /etc/resolv.conf. Rather than any single program owning DNS, openresolv acts as a central broker: Network
• OpenSSH — OpenSSH provides encrypted remote access, file transfer, and port forwarding. On Shani OS, the SSH daemon (sshd) is not enabled by default.
• PowerDNS + PowerDNS Admin — PowerDNS + PowerDNS Admin (Authoritative DNS) Purpose: Authoritative DNS server for your own domains. While Pi-hole, AdGuard, and Technitium
• Remote Desktop — Shani OS includes both client and server tools for graphical remote desktop access. All tools are pre-installed. Client — Connect to a Remot
• rsyncd (rsync Daemon) — The rsync daemon exposes file modules over the rsync:// protocol for fast, efficient network file synchronisation and backups. Unlike SSH-ba
• Samba (SMB/CIFS) — Samba provides file and print sharing using the SMB/CIFS protocol, making your Shani OS machine appear as a Windows-compatible network share
• slapd (OpenLDAP) — OpenLDAP is an open-source implementation of the Lightweight Directory Access Protocol (LDAP), used for centralised authentication and direc
• snmpd (SNMP) — The Simple Network Management Protocol daemon allows your Shani OS machine to be monitored by external systems such as Zabbix, Nagios, Libre
• SSHFS — SSHFS mounts any directory from an SSH-accessible machine as a local folder using FUSE. It requires only an SSH server on the remote — no sp
• Tailscale VPN — Tailscale builds a private, peer-to-peer encrypted network (a "tailnet") between all your devices using WireGuard under the hood. Every devi
• TCP/IP Fundamentals — TCP/IP Fundamentals The TCP Three-Way Handshake Every TCP connection opens with a three-message exchange: 1. SYN — client sends a segment wi
• Troubleshooting — Troubleshooting | Issue | Solution | |-------|----------| | TUN/TAP device not found | Run sudo modprobe tun on the host | | Clients can't r
• Virtual Networking — Linux exposes a rich set of virtual network devices and primitives for building software-defined networks, container networking, VMs, VPN tu
• WireGuard Road Warrior — Split-Tunnel — WireGuard Road Warrior (Manual Split-Tunnel Config) Purpose: A "road warrior" setup lets mobile or laptop clients connect to your home serve
• WireGuard (Manual) — WireGuard kernel support and wireguard-tools are pre-installed on Shani OS. Tailscale uses WireGuard under the hood, but you can configure r
• Wi-Fi & Wireless Firmware — Wi-Fi works on first boot. NetworkManager is preinstalled and enabled, and the wireless firmware for common chip families ships inside the i

Overview

• Overview — Comprehensive guide to the immutable Linux OS with atomic updates. Welcome to the Shanios technical documentation. This wiki provides compre

Security

• AppArmor (Mandatory Access Control) — AppArmor is a Linux Security Module that confines programs to a defined set of resources using per-application profiles. A profile specifies
• Audit (auditd) — auditd is the Linux kernel audit framework daemon. It captures security-relevant kernel events — file access, system calls, authentication,
• Security Features — Shanios implements defence-in-depth security across every layer — from firmware to userspace. All features are active from first boot with n
• Firmware Updates (fwupd) — fwupd is the Linux Vendor Firmware Service client. It downloads firmware updates for BIOS/UEFI, drives, controllers, and other hardware comp
• gen-efi Reference — gen-efi is the Shanios UKI (Unified Kernel Image) builder and Secure Boot key manager. It wraps dracut --uefi and sbsign/sbverify to produce
• Directory Encryption (gocryptfs) — gocryptfs encrypts individual directories using FUSE. Each file is stored as a separate encrypted blob, so cloud sync tools (Nextcloud, Sync
• Hardware Authentication — Shani OS ships with hardware authentication plumbing out of the box — fingerprint readers, FIDO2/U2F tokens, smart cards (PIV), and NFC toke
• Pacman Keyring & Trust Root — Shanios uses a custom pacman keyring to verify every package installed from the [shani] repository. This page explains how the trust root wo
• LUKS Management — Full-disk encryption with LUKS2 must be enabled during the Shanios installer — it is a single checkbox on the disk setup screen. There is no
• Lynis (Security Auditing) — Lynis is a security auditing tool that scans a running Linux system and produces a hardening report. It checks hundreds of items: file permi
• Permissions & Authorization — Shanios controls what a logged-in user can do — install software, format a disk, change the hostname — through a deliberate two-tier Polkit
• rkhunter (Rootkit Hunter) — rkhunter scans a system for known rootkits, backdoors, and local exploits. It checks system binaries against stored hashes, looks for suspic
• Secure Boot — Shanios ships with its own MOK (Machine Owner Key) and signs all UKI images at install time. Secure Boot can be enabled after installation t
• TPM2 Enrollment — TPM2 enrollment seals your LUKS2 disk encryption key into your machine's Trusted Platform Module. Once enrolled, the disk unlocks automatica

Self-Hosting & Servers

• AI & LLMs — Run large language models, vision pipelines, image generation, speech-to-text, and AI coding assistants entirely on your own hardware. No AP
• Backups & Storage — Backups & Sync Reliable, encrypted backup solutions and cloud synchronisation tools. Follow the 3-2-1 rule: Three copies of your data, on tw
• Business Intelligence & Analytics — Self-hosted BI platforms, data visualisation tools, SQL explorers, and analytical dashboards. Query your databases, build charts, and share
• Clusters & High Availability — Multi-node, replicated, and highly available deployments. All compose files use rootless Podman with :Z volume labels on bind mounts. Named
• Communication — Communication Self-hosted chat, push notifications, VoIP, and team collaboration platforms. Key Concepts Federation and the fediverse — Acti
• Databases — MongoDB & FerretDB — MongoDB Purpose: Flexible document database optimised for JSON-like storage, rapid development cycles, and unstructured data models. Common
• Databases — Messaging, Analytics & Specialty Stores — Apache Kafka Purpose: Distributed event streaming platform. Producers publish events to topics; consumers read them with durable, replayable
• Databases — PostgreSQL & MariaDB — CAP Theorem Quick Reference The CAP theorem states that a distributed system can guarantee at most two of three properties: Consistency (all
• Databases — Redis & Compatible Alternatives — Redis Purpose: High-performance in-memory data store used for caching, session management, message brokering, and real-time analytics. Used
• DevOps — Code Hosting & CI/CD — Table of Contents Code Hosting CI/CD Container & Image Tools Kubernetes & Orchestration HA Clusters Infrastructure as Code Artifact & Depend
• DevOps — Infrastructure as Code, Containers & Utilities — Infrastructure as Code OpenTofu / Terraform Purpose: Declarative cloud and on-premise infrastructure provisioning. OpenTofu is the open-sour
• Dev Tools — Version Control, CI/CD & Registries — Key Concepts Git internals that come up in interviews Every commit is a snapshot (not a diff), identified by a SHA-1 hash of its content, au
• Education & E-Learning — Self-hosted learning management systems, school administration platforms, collaborative tools, and knowledge-sharing apps. Run your own camp
• Finance & Accounting — Self-hosted personal finance, double-entry bookkeeping, invoicing, budgeting, stock portfolio tracking, and cryptocurrency nodes. Keep your
• Game Servers — Dedicated game servers for multiplayer gaming — hosted on your own hardware, on your own terms. No monthly fees, no player limits imposed by
• Home Automation — Smart home hubs, IoT bridges, camera NVRs, and automation pipelines — all running locally with no cloud dependency. Why local? Cloud-depende
• IoT & Sensor Data — Sensor data pipelines, MQTT brokers, time-series ingestion, industrial protocols, dashboards, alerting, and network monitoring. Everything f
• Kubernetes — GitOps & Continuous Delivery — GitOps & Continuous Delivery GitOps end-to-end workflow Separate app code from deployment config. Application repo contains code; GitOps rep
• Kubernetes — Networking & Ingress — Networking & Ingress Cilium (eBPF CNI — Primary) Purpose: High-performance CNI built on eBPF. Replaces Flannel, Calico, and kube-proxy in on
• Kubernetes — Observability (Metrics, Dashboards & SLOs) — Observability Prometheus + Grafana (kube-prometheus-stack) Grafana dashboard IDs | Tool | Dashboard ID | |------|-------------| | Longhorn |
• Kubernetes — Cluster Operations & Platform Engineering — Backup & Disaster Recovery Velero (Cluster Backup & Restore) Scheduled backups Restore etcd Snapshots (k3s) Restic (Off-Cluster File Backup)
• Kubernetes Overview — Key Concepts & Distributions — Table of Contents Core Concepts & Distributions 1. Key Concepts (Control Plane, Networking, RBAC, Storage, eBPF, GitOps, Namespaces, Labels,
• Kubernetes — Security & Policy — Security & Policy Kubernetes RBAC Pod Security Admission (PSA) Purpose: Kubernetes 1.25+ enforces security standards at the namespace level
• Kubernetes — Storage — Storage Longhorn (Distributed Block Storage) Purpose: Cloud-native distributed block storage for multi-node clusters. Provides replicated Re
• Kubernetes — Troubleshooting — Troubleshooting General cluster issues | Issue | Solution | |-------|----------| | kubectl: connection refused | sudo systemctl status k3s;
• Kubernetes — Workload Patterns — Workload Patterns StatefulSets Use for databases, Kafka, Elasticsearch, Redis Cluster — anything needing stable identity or per-pod PVCs. Jo
• Mail Servers — Production-ready email solutions for full data control and privacy. ⚠️ Prerequisite: Requires static public IP, reverse DNS (PTR), and corre
• Container Management & Lifecycle — Best practices for running, updating, and maintaining self-hosted containers on Shani OS. Key Concepts These concepts apply identically whet
• Media & Entertainment — Self-hosted streaming servers, personal photo libraries, music servers, and download automation. All containers bind to 127.0.0.1 by default
• Medical & Health — Self-hosted electronic health records, hospital information systems, FHIR servers, health data aggregation, telemedicine, and personal welln
• Monitoring — Grafana, Loki & Tracing — Grafana Purpose: The standard visualisation layer for Prometheus, Loki, InfluxDB, and 50+ other data sources. Drag-and-drop dashboards, aler
• Monitoring — Log Aggregation (ELK, OpenSearch & Vector) — Elasticsearch + ELK Stack (Single-Node) Purpose: Distributed search and analytics engine — the E in the ELK stack (Elasticsearch + Logstash
• Monitoring — Prometheus, Alerting & Long-Term Storage — Key Concepts The three pillars (now four) of observability Metrics — numeric time-series data (CPU %, request rate, error count). Cheap to s
• Monitoring — Uptime, Lightweight Dashboards & All-in-One Platforms — Netdata Purpose: Real-time system and container metrics with zero configuration. Auto-discovers running containers, processes, databases, an
• AdGuard Home — AdGuard Home Purpose: Pi-hole alternative with native DNS-over-HTTPS (DoH) and DNS-over-TLS (DoT) support, a cleaner UI, per-client rules, a
• Blocky — Blocky (Fast DNS Ad Blocker) Purpose: High-performance DNS proxy written in Go. Blocks ads and trackers via deny-lists (same blocklists as P
• ddns-updater (Dynamic DNS) — ddns-updater (Dynamic DNS) Purpose: Keeps your DNS records updated when your home/server IP changes. Polls your current public IP on a sched
• Firezone — Purpose: Zero-trust network access (ZTNA) built on WireGuard. Features SSO (OIDC/SAML), granular access policies, device posture checks, and
• frp (Fast Reverse Proxy) — frp (Fast Reverse Proxy) Purpose: Expose services running behind NAT or a firewall to the internet via a VPS relay — without needing to open
• FRRouting — BGP, OSPF & Dynamic Routing — FRRouting (BGP / OSPF / Dynamic Routing) Purpose: Full-featured open-source routing suite implementing BGP, OSPF, IS-IS, RIP, PIM, and BFD —
• Gluetun (VPN Client Container) — Gluetun (VPN Client Container) Purpose: Route any container's traffic through a commercial VPN provider — without installing a VPN client on
• HAProxy — HAProxy (High-Performance Load Balancer) Purpose: The gold-standard TCP and HTTP load balancer. HAProxy has been the backbone of GitHub, Red
• Headscale (Self-Hosted Tailscale Alternative) — Purpose: Zero-config mesh VPN built on WireGuard. Tailscale uses managed coordination; Headscale is the fully open-source self-hosted contro
• Hysteria 2 (High-Loss Networks) — Hysteria 2 (High-Loss Networks) Purpose: A QUIC-based proxy and tunnel that performs well in high-latency, high-loss, or censored network en
• Kea DHCP — Kea DHCP (Modern DHCP Server) Purpose: ISC Kea is the modern replacement for ISC DHCP (dhcpd). Provides DHCPv4 and DHCPv6 with a REST API, a
• LibreNMS — LibreNMS (Network Monitoring) Purpose: Full-featured auto-discovering network monitoring system. Discovers routers, switches, servers, APs,
• Nebula (Overlay Mesh Network) — Nebula (Overlay Mesh Network) Purpose: A scalable, decentralised overlay network developed by Slack. Nodes communicate directly using certif
• NetBird — NetBird Purpose: Open-source, peer-to-peer WireGuard mesh VPN platform. The most complete self-hosted alternative to Tailscale — management
• NetBox — NetBox (Network Documentation & IPAM) Purpose: Source of truth for your network infrastructure. Document IP address assignments (IPAM), VLAN
• Nginx Proxy Manager — Nginx Proxy Manager Purpose: GUI-based reverse proxy with Let's Encrypt integration. If you find Caddy's Caddyfile syntax unfamiliar, NPM of
• Ntopng — Ntopng (Network Traffic Analysis) Purpose: Real-time network traffic monitoring and analysis. Shows active flows, top talkers, protocol brea
• OpenVPN — OpenVPN Purpose: Legacy, highly configurable VPN standard. Use when you need specific cipher suites, client certificate management, or compa
• Outline VPN — Outline VPN Purpose: Shadowsocks-based proxy server by Jigsaw (Google). Designed for ease of deployment and resistance to traffic fingerprin
• Pangolin — Purpose: A fully open-source alternative to Cloudflare Tunnel. Expose local services via a public HTTPS URL through an encrypted WireGuard t
• phpIPAM — IP Address Management — phpIPAM (Lightweight IP Address Management) Purpose: Web-based IP address management tool. Track which IPs are assigned, to what device, who
• Pi-hole — Pi-hole Purpose: Network-wide DNS ad and tracker blocker. Runs as your LAN's DNS server and blocks ads, telemetry, and malware domains for e
• Pritunl — Purpose: Enterprise-grade VPN with a modern web UI. Supports WireGuard and OpenVPN, SSO, multi-site routing, and audit logging. Requires Mon
• SearXNG — SearXNG Purpose: Privacy-respecting meta-search engine. Aggregates results from Google, Bing, DuckDuckGo, and 70+ other sources without trac
• Squid (Caching Proxy) — Squid (Caching Proxy) Purpose: High-performance HTTP/HTTPS caching proxy. Squid caches web content so repeated requests are served from disk
• Technitium DNS Server — Technitium DNS Server Purpose: Full-featured authoritative and recursive DNS server with a clean web UI. Goes further than Pi-hole and AdGua
• Traefik — Traefik Purpose: Container-native reverse proxy and load balancer. Auto-discovers services by watching Docker/Podman labels — no config file
• Unbound — Unbound (Recursive DNS Resolver) Purpose: Validating, caching, recursive DNS resolver. Use it upstream of Pi-hole or AdGuard Home for DNSSEC
• WireGuard / WG-Easy — All VPN and tunnel solutions on this system can run fully containerised. Rootless containers handle traffic routing but require specific cap
• Xray / V2Ray — Protocol-Obfuscating Proxy — Xray / V2Ray (Protocol-Obfuscating Proxy) Purpose: A suite of network proxy tools that wrap traffic in protocols designed to evade deep pack
• ZeroTier (Self-Hosted Controller) — ZeroTier (Self-Hosted Controller) Purpose: Run a private ZeroTier network controller without using ZeroTier's central cloud servers. Manage
• OpenStack & Private Cloud — OpenStack & Private Cloud Deploy a full OpenStack cloud on this system — from a minimal all-in-one development setup to a multi-node private
• Productivity — File Sync (Nextcloud, Syncthing & More) — Key Concepts Internal Developer Platforms (IDPs) — what they solve Without an IDP, every developer needs to know: how to provision infrastru
• Productivity — Wikis & Knowledge Bases — Outline (Team Knowledge Base) Purpose: Modern wiki and knowledge base with real-time collaborative editing, a clean Notion-like interface, a
• Productivity — Notes, Bookmarks & RSS — HedgeDoc (Collaborative Markdown) Purpose: Real-time collaborative Markdown editor. Multiple people edit simultaneously — useful for meeting
• Productivity — Project Management & CRM — Planka (Kanban Board) Purpose: Open-source Trello alternative. Real-time collaborative Kanban boards with cards, labels, checklists, due dat
• Productivity — Publishing & Design Tools — Ghost (Publishing & Blogging) Purpose: Modern, open-source publishing platform. Ghost is a focused writing and newsletter tool — clean edito
• Productivity — Household & Personal Utilities — Mealie (Recipe Manager) Purpose: Self-hosted recipe manager with web scraping (import recipes from any URL), meal planning, shopping list ge
• Security & Identity — SSO, Directory & Passwordless (Authelia, Authentik, Keycloak, Zitadel, LLDAP, Kanidm) — Key Concepts Zero Trust principles "Never trust, always verify." Traditional perimeter security trusts anything inside the network. Zero tru
• Security — CrowdSec, PKI, Secrets & SIEM — CrowdSec Purpose: Collaborative intrusion prevention system. Analyses your logs for attack patterns, blocks malicious IPs via a firewall bou
• Security & Identity — Scanning, SBOM & Policy Enforcement — Syft + Grype (SBOM & Vulnerability Scanning) Purpose: Syft generates a Software Bill of Materials (SBOM) — a complete inventory of every pac

Software & Apps

• AI-Assisted Development — Shanios supports every major style of AI-assisted coding: cloud assistants (GitHub Copilot, Anthropic, OpenAI-backed tools), editor extensio
• AppImage — AppImages are self-contained executable bundles that run on any Linux system without installation. Gear Lever (pre-installed) provides a GUI
• Apptainer (HPC Containers) — Apptainer (formerly Singularity) is the container runtime built for HPC. It packages your entire software environment into a single .sif (Si
• Bottles (Windows Compatibility) — Bottles is the recommended tool for running non-gaming Windows software on Shanios. It manages Wine environments ("bottles"), handles runtim
• Containers — Shanios is a first-class container platform. The following runtimes are pre-installed and ready to use: | Runtime | Best for | Wiki | |---|-
• Development Environments — Shanios works as a daily development machine, but the workflow differs from a traditional distro: /usr is read-only and there is no package
• Distrobox — Distrobox is the recommended way to run software that requires traditional package managers on Shanios. It creates a full mutable Linux cont
• Flatpak — Flatpak is the primary method for installing GUI applications on Shanios. Flathub is pre-configured and ready to use from first boot — no se
• Gaming — Shanios pre-installs GameMode and broad controller/RGB hardware support on every edition. The full gaming app stack (Steam, Lutris, Heroic,
• GPU Acceleration & HPC Containers — Shanios is an immutable OS built for reproducibility. GPU drivers are pre-installed and OS-managed, while heavy user-space stacks (CUDA, ROC
• Homebrew — Homebrew is an optional, user-space package manager that installs software under /home/linuxbrew/. It is useful if you are familiar with mac
• LXC and LXD — LXC and LXD provide full Linux system containers — a complete operating system (init system, services, network stack) inside an isolated env
• Nix Package Manager — Nix is pre-installed on Shanios and is the recommended way to install CLI tools, language runtimes, and developer libraries. All Nix data li
• Building & Adding Packages — Shanios uses a reproducible Docker-based build pipeline to compile Arch Linux packages for the [shani] repository. This page explains how to
• Shani Platform API — platform.shani.dev is the unified backend for the Shanios commercial planes: fleet management, billing, licensing, notifications, and the or
• Shani Package Repository — The [shani] repository contains custom packages built for Shanios. It is served at repo.shani.dev and is configured on every Shanios install
• Snaps — Snap packages are sandboxed, self-contained applications published to the Snap Store by Canonical and third-party developers. Shanios ships
• systemd-nspawn — systemd-nspawn is a lightweight container mechanism built directly into systemd. It runs a full Linux distribution — complete with an init s
• Virtual Machines — Shanios ships a full virtualisation stack pre-installed and ready to use. VM disk images live in dedicated Btrfs subvolumes (@libvirt and @q
• Android (Waydroid) — Waydroid runs a full Android system in a container on Shanios. It integrates with the Wayland compositor so Android apps appear as native wi

System

• Accessibility — Shanios pre-installs a full accessibility stack on every desktop edition (GNOME, KDE Plasma, and COSMIC) — a screen reader, speech synthesis
• Audio (PipeWire) — Shanios uses PipeWire as the entire audio (and video) server on every edition — it replaces PulseAudio and JACK with a single unified daemon
• Backup & Recovery — Shanios protects the OS layer via atomic updates and Btrfs slot snapshots. User data and container state must be backed up independently to
• Command Cheatsheet — One-line-per-task reference for daily Shanios operation. Printable. Full detail lives in the pages linked at the bottom. | Task | Go-to comm
• cronie (Cron Scheduler) — cronie is the standard cron daemon — it runs commands on a schedule defined in crontab files. It is pre-installed and active by default on S
• GPU & Graphics Drivers — Every graphics driver on Shanios ships inside the signed OS image. There is no DKMS, no post-install driver script, and nothing to download
• Hardware — This page covers inspecting and diagnosing hardware on Shani OS: CPUs, memory, GPUs, storage controllers, USB devices, sensors, and firmware
• Kernel Modules — Kernel modules are loadable drivers and extensions that the Linux kernel can load and unload at runtime without rebooting. On Shani OS, modu
• Logging — Shani OS uses systemd-journald as its primary logging system. All kernel messages, service output, and system events flow into a single stru
• ch* Commands (chmod, chown, chattr, ACLs) — The ch* family covers the core "change" utilities — tools that modify permissions, ownership, file attributes, and user account properties.
• Power Management — Shanios ships sane power defaults that are active from first boot — no post-install tuning required. This page focuses on laptops: sleep sta
• Printing & Scanning — Shanios ships a complete printing and scanning stack out of the box — CUPS, a wide range of vendor drivers, and driverless IPP/network scann
• Process Management — Standard Linux process management tools are all available on Shani OS. This page covers inspecting, controlling, and debugging running proce
• Storage — This page covers raw disk and block-device management on Shani OS: inspecting drives, partitioning, filesystem operations, SMART health moni
• Systemd — Systemd is the init system and service manager on Shani OS. It starts every process at boot, manages all daemons, handles logging via the jo
• Users & Groups — User accounts on Shani OS follow standard Linux conventions — accounts are stored in /etc/passwd, /etc/shadow, and /etc/group, which live in

Troubleshooting

• Troubleshooting — The most important thing to know about troubleshooting Shanios is that the worst case is almost always "rollback and reboot." The architectu

Updates & Config

• Release Channels — Shanios publishes releases through two channels: latest and stable. This page explains the difference and how promotion works. Channel Overv
• System Config — All system configuration in Shanios follows standard Linux conventions — edit files in /etc, manage services with systemctl. Your changes ar
• shani-health Reference — shani-health is the system health and diagnostics CLI for Shanios. It provides a comprehensive single-command view of your system's state: b
• Factory Reset (shani-reset) — shani-reset wipes all persistent system state stored in /data and reboots the machine. On the next boot, systemd-tmpfiles recreates the /dat
• Shell & Environment — Shanios ships a fully configured Zsh environment with modern UX features enabled out of the box. All shell configuration lives in your home
• System Updates — Shanios updates are atomic — the running system is never modified. Updates are written to the inactive slot, verified, and activated on the
• User Provisioning (shani-user-setup) — shani-user-setup automatically provisions every regular user (UID 1000–59999) with the correct groups, default shell, Flatpak remotes, Nix c