Shani OS's root filesystem is read-only. You cannot write to /usr, /bin, or /lib at runtime — the OS is a verified, immutable image. So how do you install software?
The answer is that software belongs in one of several persistent layers, each in its own Btrfs subvolume alongside the OS. Every one of these layers survives OS updates and rollbacks completely untouched. None of them conflict.
This post is the single reference for all of them.
---
Decision Flowchart
Start here when you need to install something:
What do you need?
│
├─ A GUI desktop application
│ └─ Is it on Flathub?
│ ├─ Yes → Flatpak (flatpak install flathub ...)
│ └─ No → Is it on the Snap Store?
│ ├─ Yes → Snap (snap install ...)
│ └─ No → Is it an AppImage?
│ ├─ Yes → AppImage + Gear Lever
│ └─ No → Distrobox (install inside a container, export to launcher)
│
├─ A CLI tool or development runtime
│ └─ Is it in Nixpkgs? (search.nixos.org)
│ ├─ Yes → Nix (nix-env -iA nixpkgs.toolname)
│ └─ No → Distrobox (install via apt/pacman/yay inside a container)
│
├─ A Windows application (.exe)
│ └─ Does it work under Wine?
│ ├─ Likely yes → Bottles (Wine environment manager, pre-installed on KDE)
│ └─ Needs real Windows kernel → Virtual Machine (virt-manager / GNOME Boxes)
│
├─ A database, service, or backend
│ └─ Podman (rootless OCI containers, Docker-compatible)
│
├─ A containerised HPC/research environment for cluster use
│ └─ Apptainer (single .sif file, runs identically on any SLURM/PBS cluster)
│
├─ A full mutable Linux environment (need apt/pacman/yay/AUR)
│ └─ Distrobox (full distro package manager, home dir shared)
│
├─ A full isolated Linux system (own init, services, network)
│ ├─ Need rich tooling (image catalog, port forwarding) → LXC/LXD
│ └─ Need minimal overhead, no daemon → systemd-nspawn
│
└─ An Android app
└─ Waydroid (full hardware-accelerated Android in a container)---
The Full Comparison Table
| Ecosystem | Best for | Isolation | GUI apps | CLI tools | Root required | Survives updates | |---|---|---|---|---|---|---| | Flatpak | GUI desktop apps | Sandboxed | ✓ primary | — | No | ✓ @flatpak | | Snap | GUI apps not on Flathub | Strict/Classic | ✓ | Some | No | ✓ @snapd | | AppImage | Portable/beta apps | None (user perms) | ✓ | — | No | ✓ @home | | Nix | CLI tools, dev runtimes | None (profile) | Some | ✓ primary | No | ✓ @nix | | Homebrew | macOS muscle memory | None (user dir) | Some | ✓ | No | ✓ @home | | Distrobox | Full distro env, AUR | Low–medium | ✓ (export) | ✓ (export) | No | ✓ @containers | | Podman | Services, databases | OCI container | — | ✓ | No (rootless) | ✓ @containers | | LXC/LXD | Full system containers | High | — | ✓ | Yes (lxd group) | ✓ @lxc/@lxd | | systemd-nspawn | Lightweight system containers | High | — | ✓ | Yes | ✓ @machines | | Apptainer | HPC / cluster workloads | Read-only SIF | — | ✓ | No | ✓ ~/.apptainer | | Bottles/Wine | Windows apps | Wine prefix | ✓ | ✓ | No | ✓ @home | | Virtual Machines | Full hardware isolation | Complete (own kernel) | ✓ | ✓ | KVM group | ✓ @libvirt | | Waydroid | Android apps | LXC container | ✓ | — | Init only | ✓ @waydroid |
---
Where Each Ecosystem Lives on Disk
Every ecosystem has its own Btrfs subvolume. None overlap. All survive OS updates and rollbacks because shani-deploy only writes to @blue or @green — never to these subvolumes.
Btrfs filesystem
├── @blue / @green ← OS slots (only these change during shani-deploy)
├── @home ← /home — your files, AppImages, Homebrew, Nix profile
├── @flatpak ← /var/lib/flatpak
├── @snapd ← /var/lib/snapd
├── @nix ← /nix (shared across both OS slots)
├── @containers ← /var/lib/containers (Distrobox + Podman)
├── @machines ← /var/lib/machines (systemd-nspawn)
├── @lxc / @lxd ← LXC and LXD containers
├── @libvirt / @qemu ← VM disk images
└── @waydroid ← /var/lib/waydroid---
When to Use Each One
Flatpak — GUI applications (primary)
Flatpak is the right choice for almost every GUI desktop application. Flathub has thousands of apps — browsers, office suites, media players, creative tools, IDEs. Apps are sandboxed, auto-update every 12 hours, and their permissions are manageable via Flatseal (pre-installed).
flatpak install flathub org.mozilla.firefox
flatpak install flathub org.gimp.GIMP
flatpak install flathub com.spotify.Client
flatpak search "video editor"Guide: Flatpak on Shani OS
---
Snap — GUI apps not on Flathub
Snap is pre-configured as a fallback when an app exists only on the Snap Store. snapd.socket is socket-activated — the daemon starts on demand. Snap packages live in @snapd.
snap install some-app
snap install code --classic
snap listGuide: Snap on Shani OS
---
AppImage — portable / beta apps
AppImages are self-contained executables. Download, chmod +x, run. No installation, no system writes. Gear Lever (pre-installed on both editions) integrates them into your launcher and tracks updates.
chmod +x AppName.AppImage
./AppName.AppImage
# Or drag onto Gear Lever for launcher integrationGuide: AppImage on Shani OS
---
Nix — CLI tools and dev runtimes (primary)
Nix is pre-installed and the daemon is running. The @nix subvolume is shared between both OS slots — packages survive updates and rollbacks and are immediately available in the new slot. Over 100,000 packages. Multiple versions of the same tool coexist cleanly.
# Add a channel once (fresh install)
nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs
nix-channel --update
# Install anything
nix-env -iA nixpkgs.nodejs_22
nix-env -iA nixpkgs.rustup
nix-env -iA nixpkgs.ripgrepGuide: Nix on Shani OS
---
Homebrew — if brew is muscle memory
Homebrew installs to /home/linuxbrew/.linuxbrew — completely outside the read-only OS root. Works identically to macOS. A reasonable choice for macOS switchers; Nix is more powerful for complex environments.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install ripgrep node jqGuide: Homebrew on Shani OS
---
Distrobox — full mutable Linux environment
Distrobox creates a container of any Linux distribution — Arch, Ubuntu, Fedora — with that distro's full package manager intact. Your home directory is shared by default. Binaries and GUI apps can be exported to your host launcher. Containers live in @containers.
# Arch with AUR access
distrobox create --name arch-dev --image archlinux:latest
distrobox enter arch-dev
yay -S some-aur-package
distrobox-export --bin /usr/bin/some-tool
# Ubuntu with PPAs
distrobox create --name ubuntu-dev --image ubuntu:24.04
distrobox enter ubuntu-dev
sudo add-apt-repository ppa:some/ppa && sudo apt install some-packageGuide: Distrobox on Shani OS
---
Podman — services and databases
Podman is rootless, Docker-compatible, and daemon-free. Use it for persistent services: databases, web servers, self-hosted tools. The Pods app (pre-installed) gives you a graphical interface. podman-docker is pre-installed — existing docker commands work as-is.
podman run -d -p 5432:5432 -e POSTGRES_PASSWORD=secret postgres:16
podman run -d -p 6379:6379 redis:7-alpine
podman-compose up -d # or docker compose up -dGuide: Podman on Shani OS
---
Apptainer — HPC and cluster workloads
Apptainer (formerly Singularity) packages your entire environment into a single .sif file that runs identically on your Shani OS workstation and on any SLURM/PBS/LSF cluster. No root required. --nv and --rocm flags for GPU passthrough.
apptainer pull docker://pytorch/pytorch:latest
apptainer exec --nv pytorch_latest.sif python3 train.py
apptainer build --fakeroot myenv.sif myenv.defGuide: Apptainer on Shani OS
---
LXC/LXD — full system containers
LXD runs complete Linux OS environments — init system, services, network stack — sharing the host kernel but fully isolated. Lighter than a VM, more complete than Distrobox. lxd.socket is socket-activated.
sudo lxd init --auto
lxc launch ubuntu:24.04 myserver
lxc exec myserver -- bash
lxc config device add myserver webport proxy listen=tcp:0.0.0.0:8080 connect=tcp:127.0.0.1:80Guide: LXC and LXD on Shani OS
---
systemd-nspawn — lightweight system containers
systemd-nspawn is the lightest full-system container option. No daemon, no setup. Pull a tarball and boot it. Container filesystems live in @machines.
sudo machinectl pull-tar --verify=no \
https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-basic.tar.zst archlinux
sudo machinectl start archlinux
sudo machinectl login archlinuxGuide: systemd-nspawn on Shani OS
---
Bottles/Wine — Windows applications
Bottles manages isolated Wine environments for running Windows .exe software directly on Linux. No Windows licence or VM required for most applications. Pre-installed on KDE Plasma, available on Flathub for GNOME.
flatpak install flathub com.usebottles.bottles
# Then: Bottles → Create bottle → Run Executable → select your .exeGuide: Windows Apps on Shani OS
---
Virtual Machines — full hardware isolation
For software requiring a real Windows kernel, GPU passthrough, or a completely separate OS environment. virt-manager (pre-installed on KDE Plasma, org.virt_manager.virt-manager Flatpak on GNOME) uses QEMU/KVM for near-native performance. VM disks live in @libvirt.
Guide: Virtual Machines on Shani OS
---
Waydroid — Android apps
Waydroid runs a full hardware-accelerated Android stack in a container. Indian apps (BHIM, DigiLocker, IRCTC), streaming apps, and Android development testing all work natively on your desktop.
sudo waydroid init # one-time setup
waydroid session start
waydroid show-full-ui
waydroid app install myapp.apkGuide: Waydroid on Shani OS
---
Ecosystem Auto-Update Summary
| Ecosystem | Auto-updates? | How to manually update | |---|---|---| | Flatpak | Every 12 hours (systemd timer) | flatpak update | | Snap | Automatic (snapd daemon) | snap refresh | | AppImage | Via Gear Lever (app-specific) | Open Gear Lever | | Nix | Manual | nix-channel --update && nix-env -u '*' | | Homebrew | Manual | brew update && brew upgrade | | Distrobox | Manual per-container | distrobox enter name -- sudo apt upgrade | | Podman images | Manual | podman pull image:latest | | Waydroid | Via OTA in Android UI | Settings → System → Software Update |
The OS itself updates separately via shani-deploy and never interferes with any of the above.
---
Resources
- docs.shani.dev — full documentation for every ecosystem
- flathub.org — Flatpak app catalogue
- search.nixos.org/packages — Nix package search
- snapcraft.io — Snap Store catalogue
- appimagehub.com — AppImage catalogue
- Telegram community
---
Built in India 🇮🇳 · Immutable · Atomic · Zero Telemetry