fluxion

---

What it is

You write a YAML profile describing the machine you want. Fluxion shows you exactly what it would do, then does the parts that make sense for the host it is running on.

fluxion validate -c workstation.yaml   # is this profile sound?
fluxion dry-run  -c workstation.yaml   # what would it do?
fluxion apply    -c workstation.yaml   # do it

Nothing is guessed. Every remote artifact is pinned and verified before it runs, every privileged step is explicit, and a preview describes the same commands the real run executes — because both are produced by the same code.

Why

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 repeatable without turning your dotfiles repo into a pile of shell scripts nobody dares change.

Install

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

The script resolves the latest release, verifies its published SHA-256 before writing anything, and installs to ~/.local/bin/fluxion. It does not touch your shell startup files.

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

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

From source

git clone https://github.com/worxbend/fluxion.cr
cd fluxion.cr
shards install
shards build --release
./bin/fluxion --help

Requires Crystal 1.21 or newer.

A small profile

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

jobs:
  - name: base
    steps:
      - type: packages
        name: core-tools
        packageManager: dnf
        packages: [git, curl, jq, zsh]

  - name: development
    dependsOn: [base]
    steps:
      - type: compiled-binary
        name: kubectl
        binaryName: kubectl
        url: https://dl.k8s.io/release/v1.30.2/bin/linux/amd64/kubectl
        checksum:
          algorithm: sha256
          value: c6e9c45ce3f82c90663e3c30db3b27c167e8b19d83ed4048b61c1013f6a7c66e
        installPath: /usr/local/bin/kubectl

Packages install one process each, so one bad name never loses the rest of the list. Jobs run in dependency order, and a job whose dependency failed is reported as blocked rather than silently skipped.

There is a second frontend for ordered, host-selected plans — see docs/workstation-profile.md.

Commands

Command	What it does
apply	Execute a profile
dry-run	The same traversal with mutation switched off
plan	The execution plan, as text, table, tree, or JSON
status	What is installed, missing, unknown, or drifted
diff	Only what differs from this host
explain	Why one job or item would run or skip
doctor	Is this host ready for this profile?
lint	Profile quality and safety advice
validate	Would this profile run at all?
list	The steps a profile declares
graph	The job dependency graph (Mermaid, DOT, JSON)
kinds	The plan kinds a manifest may use
state	Inspect and edit what previous runs recorded
report	Render a report from that state
tools	The external tools Fluxion delegates to
generate	A starter profile for this machine
snapshot	A review-required inventory of this host
import	Turn what is installed into a profile
registry	Install profiles shared through a git repository
remote-ls	List what a registry offers

Full reference: docs/commands.md.

Shared profiles

Profiles you want on more than one machine can live in a git repository and be installed by id:

fluxion registry add https://github.com/you/fluxion-profiles
fluxion remote-ls
fluxion registry install workstation

Installing writes a file and stops — running it stays a separate, deliberate step. See docs/registry.md.

What it will not do

These are deliberate, and each has a reason:

• It will not run unverified bytes. Every download is HTTPS-only with no URL credentials, re-validated after each redirect, size-bounded while streaming, and digest-checked before use. A detached signature must name a signer the profile explicitly trusts — a valid signature from an unknown key is not trust.
• It will not trust PATH for anything privileged. A sudo step becomes sudo -n -- <resolved target>, where the target is a real path under a root-owned system directory with no writable ancestor.
• It will not apply as root. There is no safe way to drop back to your account for the steps that must not be root-owned.
• It will not prompt mid-run. Items marked confirm need --yes up front. A run that waits for input is a run that hangs unattended.
• It will not guess. An unanswerable probe reports unknown, not missing: absence of evidence is not evidence of absence, and reinstalling on that basis would be wrong.

Documentation

• Command reference
• Config schema
• WorkstationProfile manifests
• Registries
• Architecture
• Development

Example profiles live in examples/.

Relationship to the Java implementation

Fluxion began as a Java 25 / Mill / GraalVM project. This is a ground-up Crystal reimplementation of the same product: same profile schemas, same command surface, same trust rules.

State files written by the Java version are read directly, so upgrading does not mean reinstalling everything you already have.

Contributing

Small, boring improvements are welcome: clearer docs, more distro examples, better validation messages, more installer kinds, sharper TUI details, safer execution edges.

crystal spec                    # tests
./lib/ameba/bin/ameba src spec  # lints
crystal tool format src spec    # formatting

All three must be clean. See docs/development.md.

Licence

MIT.