Turn a fresh Linux machine into your machine.
One YAML file. One preview. One run. CLI or TUI. No mystery bash soup.

worxbend.github.io/fluxion

curl --proto '=https' --tlsv1.2 --proto-redir '=https' -sSfL https://worxbend.github.io/fluxion/install.sh | sh

---

What Is Fluxion?

fluxion is a friendly workstation bootstrapper.

You write a YAML profile that says:

• which config frontend you want: stable jobs/steps or an ordered WorkstationProfile manifest
• which packages you want
• which installer should handle them: apt, dnf, pacman, zypper, Flatpak, direct binary downloads, shell installers, Nerd Fonts, dotfiles, or commands
• which jobs depend on other jobs
• where restart or logout checkpoints belong
• what should be skipped when state or live probes show it is already installed

Then Fluxion shows you what it is about to do and runs the matching work for the current machine.

Think of it like:

"Here is my developer laptop recipe. Please apply only the parts that make sense on this distro."

Why It Exists

Fresh machines are exciting for about five minutes. Then you remember you need Git, Zsh, Docker, Flatpak apps, kubectl, Rust, fonts, dotfiles, shell setup, and that one command you always forget.

Fluxion makes that boring setup repeatable without turning your dotfiles repo into a giant pile of shell scripts.

The Vibe

• Simple YAML instead of custom bash logic everywhere
• Dry-run first so you can inspect the plan before touching the machine
• Distro-aware package steps for Ubuntu, Debian, Fedora, Arch/EndeavourOS, and openSUSE
• Many installer kinds in one profile
• State files for interrupt/resume flows
• Plain CLI output for scripts and CI
• Interactive TUI for picking jobs, steps, and entries
• Native Linux binary via GraalVM release workflow

Tiny Example

Fluxion supports two config frontends. The stable DAG-oriented schema uses jobs and steps:

profile: my-laptop
os:
  type: fedora
  release: "44"

jobs:
  - name: base-cli
    restartPolicy:
      type: none
    steps:
      - type: packages
        name: core-tools
        packageManager: dnf
        packages:
          - "@development-tools"
          - git
          - curl
          - jq
          - zsh

      - type: compiled-binary
        name: kubectl
        binaryName: kubectl
        url: https://dl.k8s.io/release/v1.30.2/bin/linux/amd64/kubectl
        checksum:
          algorithm: SHA-256
          value: c6e9c45ce3f82c90663e3c30db3b27c167e8b19d83ed4048b61c1013f6a7c66e
        installPath: /usr/local/bin/kubectl

Package managers install one item at a time. If git works but some-wrong-name fails, Fluxion still attempts the next package and reports the partial failure clearly.

The newer WorkstationProfile manifest frontend is also supported for ordered plans selected by host facts and when rules:

apiVersion: initkit.io/v1alpha1
kind: WorkstationProfile
metadata:
  name: fedora-workstation
spec:
  target:
    os:
      distribution: fedora
      release: "44"
  policy:
    continueOnError: true
  plan:
    - name: core-cli
      kind: dnf-packages
      when:
        distribution: fedora
      spec:
        actions:
          - action: check-update
        packages: [git, curl, jq]

For manifests, spec.target.os is informational metadata. The host detector and per-entry when rules decide which entries run or skip.

Install

curl --proto '=https' --tlsv1.2 --proto-redir '=https' -sSfL https://worxbend.github.io/fluxion/install.sh | sh

That always installs the newest release. The script resolves the latest tag, verifies the published SHA-256 checksum before it writes anything, installs the binary to ~/.local/bin/fluxion, and drops the example profiles and docs in ~/.local/share/fluxion. It does not touch your shell startup files; if ~/.local/bin is not on PATH it tells you the line to add.

Pin a version, or install somewhere else:

curl --proto '=https' --tlsv1.2 --proto-redir '=https' -sSfL https://worxbend.github.io/fluxion/install.sh | sh -s -- --version v1.0.3
curl --proto '=https' --tlsv1.2 --proto-redir '=https' -sSfL https://worxbend.github.io/fluxion/install.sh | sh -s -- --bin-dir ~/bin

Piping a script to a shell means trusting whatever served it. Read it first if you would rather:

curl --proto '=https' --tlsv1.2 --proto-redir '=https' -sSfL https://worxbend.github.io/fluxion/install.sh -o install.sh
less install.sh && sh install.sh

The same script ships with every release, so install.sh is also available from https://github.com/worxbend/fluxion/releases/latest/download/install.sh.

Manual download

Native Linux builds are published from tags by GitHub Actions.

Release archives are named like:

fluxion-v1.0.3-all.jar
fluxion-v1.0.3-linux-amd64.tar.gz
fluxion-v1.0.3-checksums.sha256
install.sh

When a release archive is unpacked and fluxion is on PATH:

fluxion --help
fluxion validate -c ~/.config/fluxion/default.yaml --no-tui
fluxion plan -c ~/.config/fluxion/default.yaml --show-commands --no-tui

If you are hacking on the repo, you do not need a global Mill install. The checked-in sysboot/mill launcher is enough.

Run It

Preview an example without changing your machine:

cd sysboot
./mill cli.run dry-run -c config/example-fedora.yaml --no-tui

Apply it:

cd sysboot
./mill cli.run apply -c config/example-fedora.yaml

Force plain output:

cd sysboot
./mill cli.run apply -c config/example-fedora.yaml --no-tui

Run only selected jobs:

cd sysboot
./mill cli.run apply -c config/example-fedora.yaml --phase system-foundation --no-tui

Resume from a job:

cd sysboot
./mill cli.run apply -c config/example-fedora.yaml --from-phase development --skip-already-installed

Show the saved state path:

fluxion state path default

Native Binary Workflow

From a release download:

fluxion plan -c config/example-fedora.yaml --show-commands --no-tui
fluxion dry-run -c config/example-fedora.yaml --no-tui
fluxion apply -c config/example-fedora.yaml

From source:

cd sysboot
./mill cli.run --help
./mill cli.run apply --help
./mill cli.run validate --help

Build a native image locally when GraalVM 25 is installed:

cd sysboot
./mill cli.nativeImage

The native binary lands at:

sysboot/out/cli/nativeImage.dest/native-executable

Build From Source

Requirements:

• JDK 25
• Linux for real package-manager workflows
• GraalVM 25 only if you want native-image locally

Common development commands:

cd sysboot
./mill __.compile
./mill __.test
just quality-check
./mill cli.run --help
./mill cli.run validate -c config/example-fedora.yaml --no-tui

Repository-level validation recipes run from the root checkout and use the checked-in sysboot/mill launcher by default:

just verify
just validate-configs
just native-smoke

Focused assembly and native-image builds run from sysboot/:

cd sysboot
./mill cli.assembly
./mill cli.nativeImage

Docs

• Command reference
• Config schema
• WorkstationProfile manifest reference
• Developer guide
• Testing guide
• Architecture overview
• Native image notes
• Release checklist

Copy-pasteable examples:

• Fedora
• Arch / EndeavourOS
• openSUSE
• WorkstationProfile Ubuntu
• WorkstationProfile Fedora
• WorkstationProfile Arch / EndeavourOS
• WorkstationProfile openSUSE Tumbleweed

Project Status

Fluxion is young, useful, and still moving fast. The stable schema is the jobs/steps profile format documented in sysboot/docs/config-schema.md. The newer Kubernetes-style WorkstationProfile parser path is implemented, documented in sysboot/docs/workstation-profile.md, and covered by shipped distro examples.

Dry-run and plan modes are non-mutating. Fluxion redacts sudo input, sensitive environment values, tokens, and password-like text from rendered commands, events, failure text, and TUI state.

Use dry-run. Read the plan. Then let it run.

Contributing

Small, boring improvements are welcome:

• clearer docs
• more distro examples
• better validation messages
• more installer kinds
• sharper TUI details
• safer execution edges

Start with sysboot/CONTRIBUTING.md.

---

Fluxion - because "new laptop day" should feel fun, not like archaeology.