Agama is the openSUSE installer you meet when you boot Leap 16. On Leap 16.1 its first question is new: do you want a Standard system or an Immutable one? By the end of this guide you’ll know what that choice means, how the Agama overview fits together, and how to finish an install from your own laptop’s browser or from a JSON profile.
If you used the old YaST installer, most of the decisions are the same ones you already know, just laid out on fewer screens. I went through every screen again on the Leap 16.1 offline installer with Agama 24 in November 2026, on a fresh KVM virtual machine, and the steps and screenshots below match what you’ll see.
Know what replaced YaST in openSUSE Leap 16
YaST used to do two jobs: install the system, then administer it for the rest of its life. Leap 16 splits those jobs up. Agama handles installation only, Cockpit takes over web administration after first boot, and Myrlyn covers graphical package management. So Agama is not a renamed YaST. It’s a web application built for one task, which is why it feels lighter. Everything you used to set in the YaST installer still has a place, it just lives on a single overview page now.
Agama has also changed a lot since it first shipped with Leap 16.0. The openSUSE Leap 16.1 release announcement says the installer now ships as version 24, and the live system I booted reported the same build:
agama-24+95.c7bc9ea9e-160100.7.1.x86_64
agama-web-ui-24+89.88ffaae47-160100.6.1.noarch
agama-cli-24+95.c7bc9ea9e-160100.7.1.x86_64Those three packages are the whole installer: a service that does the work, the web interface you click through, and the agama command-line client you’ll use later for profiles. If you read an older Agama guide and the screens don’t match, version 24 is why.
Download the right installer image
Leap 16.1 offers two Agama images on the get.opensuse.org download page. The offline installer is about 4.2 GiB and carries every package on the disc, so it works without a network. The online installer is around 740 MiB and pulls packages from the mirrors during the install. Pick the offline image if the machine has slow or no internet, and the online one if you’d rather download less up front. Both boot the same Agama.
One thing trips people up here. The offline ISO publishes a .sha512 file, not a .sha256. Ask the mirror for a .sha256 and curl happily saves a 404 HTML page under that name, so the check fails with “no properly formatted checksum lines found”. Grab the SHA-512 file instead:
curl -LO https://download.opensuse.org/distribution/leap/16.1/offline/Leap-16.1-offline-installer-x86_64.install.iso
curl -LO https://download.opensuse.org/distribution/leap/16.1/offline/Leap-16.1-offline-installer-x86_64.install.iso.sha512
sha512sum -c Leap-16.1-offline-installer-x86_64.install.iso.sha512A good download prints a single OK line. Anything else means a broken or partial file, so download it again before you write it to a USB stick:
Leap-16.1-offline-installer-x86_64.install.iso: OKWrite the image to a USB drive with dd, Fedora Media Writer or balenaEtcher, or attach it as a virtual CD if you’re installing a VM. On boot you get a short GRUB menu with Install Leap 16.1 (x86_64) highlighted and a 60 second countdown:
Press Enter on the first entry and Agama loads in about a minute. Planning to drive the install from another computer? Press p on this menu first. It’s a hidden hotkey: GRUB asks you twice for a root password for the live installer, and that password is what you’ll type to log in remotely. You can skip it for a local install.
Choose Standard or Immutable mode
The first Agama screen is now called Select a mode. On Leap 16.0 this screen offered two products, full Leap 16.0 and openSUSE Leap Micro. On Leap 16.1 there’s one product, Leap 16.1, with the badge “2 modes available”, and the modes appear once you select it. Leap Micro is gone as a separate product: the release announcement says Immutable mode replaces it and there will be no Leap Micro 6.3 or 7.0.
- 1Leap 16.1
- 2Standard
- 3License checkbox
- 4Select Standard Leap 16.1
Work through the screen in this order:
- You click Leap 16.1 so the two mode buttons appear under it.
- You pick Standard for a normal desktop or server, or Immutable for a read-only system with atomic updates.
- You tick the License checkbox, “I have read and accept the license for Leap 16.1”.
- You click Select Standard Leap 16.1, a button whose label follows the mode you picked.
The button stays grey with “Select a product mode to continue” until you’ve picked a mode and accepted the license, so if nothing happens when you click, look for the unticked box. The table below sums up what each mode gives you, based on Agama’s own labels and the 16.1 release notes:
| Question | Standard | Immutable |
|---|---|---|
| Agama’s description | Standard system | Immutable system with atomic updates |
| Root filesystem | Read-write Btrfs with snapshots | Read-only, a new snapshot per update |
| How you add software | zypper as usual | transactional-update, Podman, Distrobox or Flatpak |
| Closest earlier release | Leap 16.0 | openSUSE Leap Micro |
| Pick it for | Desktops and general servers | Container hosts, VM hosts and edge boxes |
If you’re not sure, choose Standard. It behaves like every Leap you’ve used, and the rest of this guide follows it. Immutable is a great fit for a box that only runs containers. It does change how you install packages, though, so it gets its own walkthrough: the openSUSE Leap Immutable install guide covers that mode screen by screen, and the Immutable mode explainer covers how its snapshots and rollbacks work.
Work through the installation overview
Once you’ve selected a mode, Agama takes you to the Installation page. This is the biggest visual change in Agama 24: the left sidebar from Leap 16.0 is gone, and every section now sits on one page as a heading you can click. You’ll see System, Language and region, Network, Software, Storage and Authentication, plus a System Information box with the machine’s model, CPU, memory and IP addresses.
- 1Software
- 2Storage
- 3Authentication
- 4Install
Each heading opens its own page, and you come back here with the Installation link at the top. Agama fills in sensible defaults, so you only visit the sections where you want something different:
- You open Software if you want a desktop, because the default is “No desktop selected”.
- You open Storage to check which disk Agama picked and whether it plans to erase anything.
- You open Authentication every time, since the install can’t start until a user, a root password or an SSH key exists.
- You check Language and region too, because the timezone defaulted to Europe/Berlin.
Until Authentication is done, the Install button stays grey and the page says “Fix invalid settings before starting the installation”, with a warning triangle next to Authentication. It is normal on a fresh boot, not an error you caused. Under Software, notice that SELinux Support is already one of the selected patterns, which matches Leap 16 running SELinux in enforcing mode by default.
Pick a desktop in Software
A Standard install with no desktop is a lean server: Agama reported 2 additional patterns and 2.02 GiB of space. For a workstation, open Software, click Select a desktop, and you get three choices under Graphical Environments: GNOME Desktop Environment (Wayland), KDE Applications and Plasma Desktop, and an XFCE variant that Agama itself labels experimental on Wayland.
- 1KDE Applications and Plasma Desktop
- 2Accept
For this walkthrough the pick was KDE Applications and Plasma Desktop, confirmed with Accept. The overview then showed the desktop, 4 additional patterns and a requirement of 5.50 GiB, so a 20 GiB disk is a tight fit once updates and snapshots pile up. Give a desktop install at least 40 GiB and you will not have to think about it. You don’t have to touch Change patterns unless you already know you want something extra, since you can add software with zypper after the first boot.
Review the storage layout
Open Storage before you install anything, even on a blank disk. Agama shows its plan in two halves: Settings at the top, where you change what it does, and Result underneath, which lists every action it’ll take. On my 40 GiB disk the Standard mode proposal looked like this:
- 1Installation disk
- 2Encryption
- 3Actions
The Installation disk line reads “Use disk sdb (40 GiB) to install and boot”. The Actions tab lists the steps: a new GPT, a 512 MiB EFI partition with vfat, a 37.50 GiB Btrfs root and a 2 GiB swap partition. Below those sit 9 Btrfs subvolume actions you can expand. If the machine has more than one disk, click the disk line and make sure it’s the one you mean to wipe. The overview’s “No data loss is expected” line comes from these planned actions, so if Agama ever plans to delete something, that line tells you.
Full-disk encryption lives on the Encryption tab next to Installation devices, and the Boot options tab is where you’d move the bootloader. For a single-disk laptop the default layout is right, and the Btrfs root is what lets snapper roll you back after a bad update later.
Create your administrator user
Authentication is the one page you cannot skip. Agama 24 opens it with a red banner, “Defining a user, setting the root password or a SSH public key is required”, and the Root login method set to Disabled. That default is deliberate: you get a normal user who runs admin commands with sudo, and root has no password to guess.
- 1Define an administrator user
- 2Username
- 3Password
- 4SSH Public Keys
Fill the page in this order, then confirm:
- You tick Define an administrator user to reveal the account fields.
- You type a full name and a short lowercase Username, such as lorna.
- You enter the Password twice, once in each box.
- You paste a key into SSH Public Keys and press Enter if you want to log in over SSH without a password.
- You scroll down and click Accept at the bottom of the page.
The SSH key field is worth using on any server. Back on the overview, Authentication now reads “Using lorna account” with “Public key provided”, the warning is gone, and the button has changed to Install now.
Start the install and reboot
Click Install now and Agama asks one last time. The dialog is short, “Confirming starts the installation immediately with the defined settings”, so this is your final chance to cancel before the disk is partitioned.
Click Confirm and install. Agama moves through three stages, Prepare the system, Install software and Configure the system, and shows the package it’s on with a step counter. My KDE install had 4,406 steps:
The whole KDE install took about 10 minutes on a VM with 4 GiB of RAM, all of it from the offline ISO. When it’s done you get a plain Installation complete screen with a single Reboot button:
Click Reboot and remove the USB stick, or detach the ISO from the VM, so the machine starts from its new disk. A KDE install lands on the Plasma login screen with your full name already listed:
Two details on that screen are worth a second look. The clock read 7:24 PM when it was 9:24 PM in Nairobi. That’s the Europe/Berlin default from the overview, so change it in Language and region before you install if you do not live on Berlin time. And the bottom bar says Desktop Session: Plasma (X11); a Plasma (Wayland) session is installed too, and you can switch to it from that menu before you sign in.
To confirm the install did what the overview promised, log in over SSH with the key you added and run a few quick checks:
cat /etc/os-release | head -2
lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINTS
id
sudo snapper listThe trimmed output below shows only the target disk, which was sdb in this lab because the installer sat on sda; yours may be sda, vda or nvme0n1. The partitions match the storage proposal exactly, the Btrfs subvolumes are mounted, and snapper already holds the first root snapshot you can roll back to:
NAME="openSUSE Leap"
VERSION="16.1"
NAME SIZE FSTYPE MOUNTPOINTS
sdb 40G
├─sdb1 512M vfat /boot/efi
├─sdb2 37.5G btrfs /srv
│ /usr/local
│ /var
│ /opt
│ /boot/grub2/i386-pc
│ /root
│ /home
│ /boot/grub2/x86_64-efi
│ /.snapshots
│ /
└─sdb3 2G swap [SWAP]
uid=1000(lorna) gid=1000(lorna) groups=1000(lorna),496(wheel) context=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
# │ Type │ Pre # │ Date │ User │ Used Space │ Cleanup │ Description │ Userdata
───┼────────┼───────┼──────────────────────────┼──────┼────────────┼─────────┼───────────────────────┼─────────
0 │ single │ │ │ root │ │ │ current │
1* │ single │ │ Tue Nov 3 19:12:48 2026 │ root │ 5.63 GiB │ │ first root filesystem │Your user sits in the wheel group, which is what gives it sudo, and sudo asks for your own password, not root’s. The root account is locked, just as the Disabled setting promised: passwd -S root reported root L. The context= part of the id line shows SELinux is active, and /sys/fs/selinux/enforce read 1, so it’s enforcing. The installed system pulled in 2,187 packages with Plasma 6.6.4 and kernel 6.12. If the hostname matters to you, set it under System before installing, because the lab machine came up as localhost.localdomain.
Install remotely from your browser
Everything above can happen from a different computer, which is Agama’s best trick. The installer is a web application served over HTTPS, so a headless server, a rack machine or a VM on a remote host can be installed from your laptop. The live system lists the addresses on its text consoles. Mine showed these lines:
Welcome to Agama installer version 24+95.c7bc9ea9e! (\l)
Agama installer SSL certificate fingerprints:
SHA256: 29:A8:42:3D:41:CB:6C:75:1D:8A:27:95:95:D3:00:FC:53:09:2B:5D:9B:3F:6D:90:16:B4:5F:6C:FE:3E:87:24
SHA1: 8D:4D:D4:07:DE:BD:CF:83:04:09:20:5E:C5:62:65:06:02:C7:E7:51
Connect to the Agama installer using these URLs:
https://agama.local
https://10.0.1.50Open either URL in your browser. Use the IP address on any network you don’t fully trust, because Agama’s own remote-install guide warns that a spoofed .local answer could capture the root password you’re about to type. The certificate is self-signed, so your browser will warn you: compare the SHA256 fingerprint it shows with the one on the console, and accept it only if they match. The agama.local name only works when your network passes mDNS.
- 1Password
- 2Log in
Type the live password you set with the p hotkey into the Password box and click Log in. The hotkey only adds live.password= to the installer’s kernel line, so that password lives in the installer’s RAM and never lands on the installed system. If you skipped the hotkey, Agama’s documentation says the live system generates a random root password and prints it on the console just above the login prompt, so read it from the machine’s screen instead. After logging in you get the same Select a mode screen and the same overview you’d see on the machine’s own screen.
Automate it with a profile
Clicking through Agama once is pleasant. Doing it for the tenth identical server isn’t. Every choice you make in the browser is stored as a JSON profile, and the agama client prints it. Log in to the live installer over SSH as root with the same live password and run:
agama config showThe output is the whole install in a few lines. Notice "mode": "standard" under product, which is how a profile picks between Standard and Immutable:
{
"product": {
"id": "openSUSE_Leap",
"mode": "standard"
},
"software": {
"patterns": {
"add": [
"selinux",
"kde"
],
"remove": []
}
},
"user": {
"fullName": "Lorna Chepkoech",
"password": "Leap-lab-2448!",
"hashedPassword": false,
"userName": "lorna",
"sshPublicKeys": [
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIONFLnvw1dCmrinWGKaiBmzP796h3raxjcYOm1la7nko engine-job-2448"
]
}
}Look closely at the user block: the password comes out in plain text with "hashedPassword": false. Before you save this profile anywhere shared, replace it with a hash from openssl passwd -6 and set hashedPassword to true. Then save the profile and check it against Agama’s schema before you rely on it:
agama config show > /root/profile.json
agama config validate /root/profile.json
agama statusA valid profile prints nothing from validate and exits with code 0, and agama status answered “Ready to start the installation.” on my machine. To use a profile on another box, host the file on a web server and add inst.auto= with its URL to the installer’s kernel line, as described in the Agama boot options reference. An unattended install reboots by itself when it finishes. Keep in mind that a profile taken straight from config show has no storage section, so on another machine Agama proposes and uses its default disk. The simplest way to run these commands is plain ssh [email protected] into the live installer, as above. The client can also work from your own machine if it has the agama-cli package, with --host and --insecure placed before every subcommand, starting with agama --insecure --host https://10.0.1.50 auth login.
Fix the two messages that block the install
Only two messages block the install, and both are Agama telling you a required setting is missing rather than a fault on your machine.
“Fix invalid settings before starting the installation”
This shows under a grey Install button on the overview. Look for the section with a warning triangle instead of its usual icon, and open it. On a fresh boot it’s Authentication, and filling in that page clears the message.
“Defining a user, setting the root password or a SSH public key is required”
This banner sits at the top of the Authentication page until you give Agama at least one way to log in. Ticking Define an administrator user and filling in a password is enough. If you’d rather keep a root account, switch Root login method away from Disabled and set its password or key on the same page.
For a second worked example of the same installer, the step-by-step Leap 16 install guide walks through a full desktop install. Once your new system is up, the things to do after installing openSUSE Leap guide picks up from the first login, and Cockpit on openSUSE Leap covers the web administration half that YaST used to handle. If you’re coming from an older release instead of a clean install, the Leap 15 to Leap 16 upgrade guide is the path that keeps your data in place.
