Skip to main content

Knuckle

Knuckle is an interactive TUI installer for Flatcar Container Linux — the CNCF-hosted, immutable, container-optimized OS. It gives you an Ubuntu-style guided install experience without requiring you to write Ignition configs by hand.

Think of it as Bluefin for your home server or bare-metal cluster node.

Early release

Knuckle is pre-alpha. All feedback and contributions are welcome at projectbluefin/knuckle.

Why Flatcar?​

Flatcar is in the CNCF — a vendor-neutral foundation that means long-term stability. It's designed to run anything: plop anything from linuxserver.io on it, build a home NAS, set up a k8s cluster, or run a personal cloud. The Flatcar Bakery provides system extensions for Docker, Kubernetes, Tailscale, NVIDIA drivers, and more.

Requirements​

ComponentRequirement
Architecturex86_64 or ARM64
BootUEFI only (no legacy BIOS)
StorageOne target disk (single-disk install)
NetworkDHCP or static IPv4
RAM2 GB minimum

  1. Download the installer ISO from the knuckle releases page — pick knuckle-installer-stable.iso for amd64 or the arm64 variant.

  2. Write to USB using your preferred tool:

    # Linux/macOS
    sudo dd if=knuckle-installer-stable.iso of=/dev/sdX bs=4M status=progress

    Or use Fedora Media Writer / Balena Etcher.

  3. Boot from the USB. Knuckle starts automatically and walks you through a 9-step guided wizard:

    • Welcome → Network → Storage → User → System Extensions → Update Strategy → Review → Install → Done

  4. Follow the wizard. You'll configure your hostname, timezone, disk, network, SSH keys (fetched from GitHub or entered manually), and any system extensions from the Flatcar Bakery.

  5. Review the generated Butane config before confirming — then Knuckle handles the rest.

After install, you'll have a pristine upstream Flatcar Linux system.

Headless / automated installs​

For CI/CD or scripted bare-metal provisioning, Knuckle supports a fully unattended install via a JSON config file:

knuckle --headless --config install.json

Minimal install.json:

{
  "hostname": "flatcar-01",
  "disk": "/dev/disk/by-id/ata-SomeSeagate_1TB",
  "channel": "stable",
  "network": {"mode": "dhcp"},
  "users": [
    {
      "username": "core",
      "ssh_keys": ["ssh-ed25519 AAAA..."]
    }
  ]
}

For the full config schema — static IP, sysexts, Tailscale, swap, NVIDIA drivers, external Ignition URL — see docs/HEADLESS-CONFIG.md in the knuckle repo.

Further reading​