Knuckle#

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

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#

Installing from the ISO (recommended)#

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

2. Verify the ISO (optional but recommended). Each release is signed with cosign keyless signing via GitHub Actions OIDC. After downloading the ISO and its .bundle file:

   ⧉

   cosign verify-blob \
     --bundle knuckle-installer-stable.iso.bundle \
     --certificate-identity-regexp \
       "https://github.com/projectbluefin/knuckle/.github/workflows/release.yml@refs/tags/.*" \
     --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
     knuckle-installer-stable.iso
   

   A Verified OK result confirms the ISO was produced by the official release workflow and has not been tampered with.

3. 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.

4. 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

5. 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.

6. 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..."]
    }
  ],
  "update_strategy": "reboot"
}

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#

• knuckle README — CLI flags, architecture overview, VM testing
• HEADLESS-CONFIG.md — complete headless JSON schema reference
• SECURITY.md — supply-chain verification and release signing
• Flatcar docs — upstream OS documentation
• Flatcar Discord — community chat