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
Copy-pasteable examples:
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.
