Installation

ShivaOS Atomic is distributed as a bootable ISO image. You need a USB drive of at least 8 GB and a UEFI-compatible PC.

Requirements

Installation steps

First boot

On the first boot, ShivaOS automatically compiles GPU drivers and runs the welcome wizard.

Welcome wizard

The Shiva Welcome wizard guides you through 6 steps: Welcome, GPU, Apps, Controller, Wallpaper, and Ready. At the end, the system reboots automatically to apply all settings.

Set hostname (recommended)

To avoid potential KDE/Wayland issues, set a hostname after first boot:

sudo hostnamectl set-hostname shivaos

Updates

ShivaOS Atomic uses rpm-ostree for system updates. Unlike traditional package managers, updates are applied atomically — the old system is preserved and can be restored instantly.

Manual update

rpm-ostree upgrade

systemctl reboot

Rollback

If something goes wrong after an update, roll back to the previous version:

rpm-ostree rollback

systemctl reboot

Check status

rpm-ostree status

Steam & Proton

Steam and Proton are pre-installed. Most Windows games run out of the box via Proton.

Enable Proton for all games

Proton-GE (better compatibility)

Install Proton-GE from Shiva Store → Proton-GE tab for improved game compatibility.

Useful launch options

Performance

ShivaOS includes performance tools pre-configured. Here's how to use them.

MangoHUD

MangoHUD shows real-time FPS, CPU, GPU and RAM usage. Enable it per game with the launch option above, or globally:

MANGOHUD=1 steam

GameMode

GameMode optimises CPU scheduling and power profile when a game is running. It activates automatically with the gamemoderun launch option.

Kernel CachyOS BORE

ShivaOS uses the CachyOS kernel with BORE scheduler and ntsync support — optimised for low-latency gaming. No configuration needed, it works automatically.

NVIDIA

NVIDIA drivers are handled automatically by akmod-nvidia. The proprietary driver compiles on first boot.

Shiva Nvidia tool

Open Shiva Nvidia from the app menu to switch between open-source (nouveau) and proprietary drivers, or repair the driver installation.

Manual repair

If drivers fail to load after an update:

sudo akmods --force
sudo dracut --force
sudo systemctl reboot

Legacy GPUs (GTX 700 and older)

GTX 700 series and older are no longer supported by recent NVIDIA drivers. Shiva Nvidia will display a warning. Use the open-source nouveau driver instead.

Atomic & rpm-ostree

ShivaOS is an immutable distribution. The root filesystem is read-only. This means the system cannot be broken by a bad update or misconfiguration.

Common commands

Installing apps

On an immutable system, the recommended way to install apps is Flatpak. System packages can be layered with rpm-ostree.

Flatpak (recommended)

flatpak install flathub com.example.App

Use Shiva Store to browse and install Flatpak apps with a graphical interface.

rpm-ostree (system packages)

rpm-ostree install package-name
systemctl reboot

Troubleshooting

Black screen on first boot (NVIDIA)

Wait 2–3 minutes. akmod-nvidia is compiling the kernel module. If it persists after a second reboot, run:

sudo akmods --force && sudo dracut --force

KDE freezes after screen lock

Set a hostname to fix a D-Bus context issue:

sudo hostnamectl set-hostname shivaos

Update failed / system broken

Roll back to the previous working deployment:

rpm-ostree rollback && systemctl reboot

Shiva AI returns 403 error

Check your internet connection. The AI uses a secure proxy at shivaos.com. If the issue persists, check that your system time is correct.

Game won't launch via Proton

Try switching to a different Proton version, or install Proton-GE from Shiva Store. Add PROTON_LOG=1 %command% as launch option to see logs.