Getting Started

First Boot Checklist

Complete these steps after your first boot to get your system configured properly.

1. Complete Initial Setup

Follow the GNOME/KDE initial setup wizard to configure your language, timezone, and user account.

2. Run Your First Update

Open a terminal and update your system to the latest image.

helper update

3. Add Helper Alias (Optional - Bash Users)

Make the helper command easier to access from Bash.

helper add-helper

Zsh users already have helper available by default.

4. Configure Git (If You're a Developer)

Set up Git with your username, email, and SSH signing.

helper setup-git

5. Install Nix (Optional but Recommended)

Get access to 80,000+ packages with pre-configured Nix.

            helper install-nix
helper setup-nixmanager
helper add-nixmanager  # Bash users only
          

6. Install Additional Software

Install gaming tools, development tools, or multimedia applications as needed.

            helper install-gaming      # Steam, Heroic, Lutris, etc.
helper install-multimedia  # Audacity, Blender, GIMP, etc.
          

7. Apply SoltrOS Theme (Optional)

Apply the official SoltrOS theme to your desktop environment.

            # For KDE Plasma:
helper apply-soltros-look_plasma

# For COSMIC:
helper apply-soltros-look_cosmic
          

8. Reboot

After updates and installations, reboot to apply all changes.

systemctl reboot

Understanding SoltrOS

What Makes SoltrOS Different

SoltrOS is an immutable Linux distribution, which means:

Your base system is read-only - System files cannot be accidentally modified or corrupted
Updates are atomic - Either the entire update succeeds or nothing changes
Rollback is instant - Boot the previous version from GRUB if something goes wrong
Software installs differently - Use Flatpak, Nix, Homebrew, or containers instead of system packages

💡 Coming From Traditional Linux?

You can't use DNF or modify /usr directly. Instead, install applications via Flatpak (GUI apps), Nix (everything), or Distrobox (full Linux distros in containers). System packages are part of the image and updated atomically.

The Helper Tool

helper.sh is your main interface for managing SoltrOS. It handles system updates, software installation, configuration, and more.

      helper              # Show all available commands
helper update        # Update system and all software
helper clean         # Clean up system cache
helper install-nix   # Install Nix package manager
    

Learn more about Helper →

Package Management

Which Package Manager Should I Use?

Flatpak

For GUI applications. Sandboxed and secure. 47 apps pre-installed.

flatpak install flathub firefox

Nix

For everything else. 80,000+ packages. Requires one-time setup.

nixmanager install firefox

Homebrew

For CLI tools and development packages. Familiar to macOS users.

brew install htop

Distrobox

Full Linux distributions in containers. For packages not available elsewhere.

helper setup-distrobox

View all system packages →

Common Tasks

Updating Your System

Run updates regularly to get the latest system image, Flatpak apps, and container updates.

helper update

This updates your system image with bootc, all Flatpaks, and any Distrobox/Toolbox containers.

Installing Software

Use the appropriate package manager for what you need:

      # GUI applications via Flatpak
flatpak install flathub org.gimp.GIMP

# Development tools via Nix
nixmanager install nodejs

# System utilities via Homebrew
brew install ripgrep

# AppImages via Gear Lever (pre-installed Flatpak)
    

Managing Flatpak Permissions

Flatpak apps are sandboxed. Use Flatseal (pre-installed) to manage permissions.

Open Flatseal from your application menu
Select the application you want to configure
Adjust filesystem access, network, and device permissions

Switching Desktop Environments

SoltrOS makes it easy to try different desktop environments.

      # Switch to COSMIC (LTS)
helper change-to-stable cosmic

# Switch to GNOME (Unstable)
helper change-to-unstable gnome

# Return to KDE Plasma (LTS)
helper change-to-stable kde
    

Your data is preserved during the switch, and you can always roll back if needed.

Switching Release Tracks

Choose between stable (LTS) and testing (Unstable) releases.

      # Switch to LTS (stable, current Fedora release)
helper change-to-stable

# Switch to Unstable (next Fedora version in testing)
helper change-to-unstable
    

⚠️ About Unstable

The Unstable track uses the next Fedora version currently in development (like Fedora 43 while 42 is the stable release). Think Debian Testing rather than Sid - it's newer packages but not the bleeding-edge chaos of Rawhide. Still, expect occasional issues.

Switching Shells

SoltrOS includes Zsh (default with Oh My Zsh), Fish, and Bash.

      helper change-to-fish  # Switch to Fish
helper change-to-bash  # Switch to Bash
helper change-to-zsh   # Return to Zsh
    

The appropriate configuration is downloaded and applied automatically.

Gaming on SoltrOS

Pre-Installed Gaming Tools

SoltrOS includes everything you need for gaming:

Steam - Already installed with Proton for Windows games
Heroic Games Launcher - Epic and GOG support
Lutris - Universal game launcher
GameMode - Automatic performance optimization
MangoHud - In-game performance overlay
CoreCtrl - GPU overclocking and fan control

Enabling AMD GPU Overclocking

If you have an AMD GPU and want to overclock:

helper enable-amdgpu-oc

Reboot after running this command. Then use CoreCtrl to adjust clocks and fan curves.

Installing More Games

Install additional game launchers and emulators:

helper install-gaming # Installs Steam, Heroic, Lutris, etc.

Development on SoltrOS

Setting Up Git

Configure Git with SSH signing for secure commits:

helper setup-git

This sets up your username, email, SSH key, and configures Git to sign commits with SSH.

Using Distrobox for Development

Distrobox lets you run full Linux distributions in containers:

      # Create Ubuntu and Arch containers
helper setup-distrobox

# Enter Ubuntu container
distrobox enter ubuntu-dev

# Install packages inside container
sudo apt install build-essential
    

Containers have access to your home directory, so your files are accessible inside.

Container Tools

SoltrOS includes comprehensive container tools:

Podman - Docker-compatible container engine (pre-installed)
Podman Desktop - GUI for managing containers (pre-installed Flatpak)
Buildah - Build OCI images
Skopeo - Work with container registries

Unblocking Docker Hub

SoltrOS blocks unapproved container registries by default for security. To use Docker Hub:

helper unblock-docker

⚠️ Security Note

This allows containers from any registry, including potentially untrusted sources. Only enable this if you understand the security implications.

Troubleshooting

System Won't Boot After Update

At the GRUB bootloader, select the previous system version
Once booted, report the issue on GitHub
The previous version will work until the issue is fixed

Application Won't Launch

If a Flatpak app won't launch, check permissions:

Open Flatseal
Find the application
Enable necessary filesystem access or permissions

Nix Packages Not Showing in Menu

After installing GUI apps with Nix, desktop shortcuts should appear automatically. If they don't, log out and back in.

Running Out of Disk Space

Clean up old system versions and unused Flatpaks:

helper clean

Need More Help?

Visit the SoltrOS Wiki for detailed documentation, or open an issue on GitHub.

✓ You're Ready!

You've completed the getting started guide. Explore the system, install your favorite applications, and enjoy your immutable SoltrOS experience!

Getting Started with SoltrOS