First installation

NOTE

Install uCore on your machine. You need a Butane file and its compiled Ignition configuration. There is no uCore graphical installer. Test the configuration in a VM first, and back up anything on the disk you intend to install to.

Before you begin

Have console access, a network connection for first boot, an SSH public key, and a dedicated target disk. Prepare the configuration on another computer with Podman or Docker; these examples use Podman.

Choose your uCore image. The examples use ghcr.io/ublue-os/ucore:stable. The registry manifest selects x86_64 or aarch64 automatically; the Fedora CoreOS installation media still needs to match your machine’s architecture.

For a UEFI system using Secure Boot, follow the enrollment guide. The documented fresh-install path temporarily disables Secure Boot so you can reach uCore and enroll its signing key.

Prepare your Butane configuration

Download the project’s auto-rebase Butane template and save it as ucore-autorebase.butane. You can also inspect the upstream source.

1. Replace YOUR_SSH_PUB_KEY_HERE with your SSH public key.
2. Replace YOUR_GOOD_PASSWORD_HASH_HERE with a password hash. Follow the Butane authentication example; do not put a plaintext password in the hash field.
3. If you chose a different image, replace both occurrences of ghcr.io/ublue-os/ucore:stable with the same image reference. They belong to two different rebase stages.

Read the full file before using it. Add any machine-specific networking or storage configuration you need. Protect the configuration: it contains access information and may contain other secrets you add.

Compile it to Ignition

Run this on your preparation computer from the directory containing the Butane file. The container reads from standard input, so no host directory mount is needed.

shellPreparation computer / compile configurationCOPY

$ podman run --interactive --rm quay.io/coreos/butane:release \    --pretty --strict < ucore-autorebase.butane > ucore-autorebase.ign

Proceed only if Butane exits successfully. Correct validation errors in the Butane source and compile again. Ignition is the resulting JSON configuration, not a file to edit by hand.

Install with CoreOS tooling, then switch to uCore

Download the appropriate live ISO from Fedora CoreOS and boot it on your target machine. Follow the Fedora CoreOS bare-metal guide. Copy ucore-autorebase.ign into the live environment’s current directory.

NOTE

Confirm the target disk. The command below installs to the disk you name and can destroy existing data on it. Replace /dev/REPLACE_WITH_TARGET_DISK with your actual OS disk; it is deliberately not a usable device name.

shellLive ISO / install to the confirmed target diskCOPY

$ sudo coreos-installer install /dev/REPLACE_WITH_TARGET_DISK \    --ignition-file ucore-autorebase.ign

After the installer reports success, remove or detach the installation media and reboot.

shellLive ISO / reboot after installationCOPY

$ sudo systemctl reboot

For cloud and hypervisor images, supply Ignition using the platform’s provisioning mechanism instead. The Fedora CoreOS platform guides cover those paths.

What happens on first boot

1. Fedora CoreOS applies the Ignition configuration.
2. The first service rebases to your chosen uCore image using the initial unverified-registry reference, then reboots.
3. The second service switches to the signed image reference now that uCore’s verification policy is present, then reboots again.

The result is a uCore system, with uCore’s software and update behavior. Allow both stages to finish and keep networking available. If a stage fails, inspect the console and the corresponding service journal; do not assume the later signed stage has run.

Confirm you reached uCore

Sign in as core using the SSH key or password you configured. Check the booted image and both service journals.

shellInstalled system / deployment and provisioning statusCOPY

$ sudo rpm-ostree status$ sudo journalctl \    -u ucore-unsigned-autorebase.service \    -u ucore-signed-autorebase.service \    --no-pager

The booted deployment should be your selected uCore image with the signed reference. Confirm the signed stage succeeded. If using Secure Boot, enroll the key before turning Secure Boot back on.

You can independently verify the published image on a computer with cosign installed:

shellComputer with cosign / verify the default imageCOPY

$ cosign verify \    --key https://github.com/ublue-os/ucore/raw/main/cosign.pub \    ghcr.io/ublue-os/ucore:stable

This verifies the image signature. It does not enroll a Secure Boot key, audit your configuration, or verify a particular architecture’s SBOM. For that, follow the digest-specific provenance instructions.

Once you have a working deployment, read Fedora’s manual rollback guidance and the deployment-pinning instructions linked by the project. Configure your shares, services, and backups deliberately; most added services are not enabled automatically.

Already have a running system?

• Fedora CoreOS: use the existing-CoreOS path, including the initial rebase, reboot, signed-reference rebase, and second reboot.
• uCore managed with bootc: use the existing-uCore bootc path. Confirm the system is healthy and its container-signing policy is intact.
• uCore still managed with rpm-ostree: use the signed rpm-ostree path. Do not guess which update manager applies.
• Fedora Atomic desktop or Fedora IoT: a direct rebase to uCore is unsupported. Use the CoreOS installer to reinstall with the uCore auto-rebase configuration, which switches the machine to uCore on first boot.

Choose the applicable transition instructions.

Source: uCore installation guide and auto-rebase example, Butane, and Fedora CoreOS provisioning documentation. Checked September 18, 2026. Commands are documented from these sources and have not been exercised on real hardware by this site build.