docs(install): CLI-233 Trust floxhub-1 for Nix installs

[flox-forge-agent]

Nix installs of Flox — nix profile install, nix-darwin, NixOS — don't trust floxhub-1, the key FloxHub-hosted catalogs sign published packages with. Installing a published package on one of those systems fails as untrusted, with no doc pointing at the fix. This adds floxhub-1 alongside the existing flox-cache-public-1 cache key in every Nix trust-configuration example on the install and troubleshooting pages, and adds a section to the signing-keys page that names the default key and gives the nix.conf and nix.settings fix inline.

Delegated by bill@flox.dev via CLI-233

The Flox installer trusts floxhub-1 out of the box, but a system that got Nix some other way never receives it. Flox's own error for this case (Package '<name>' is not signed by a trusted key., confirmed against cli/flox-rust-sdk/src/providers/buildenv.rs in flox/flox) already links to the signing-keys page, which didn't mention floxhub-1 at all.

Every code block that lists flox-cache-public-1 in a Nix trust-configuration example — /etc/nix/nix.conf lines, flake nixConfig, NixOS/nix-darwin nix.settings — now lists floxhub-1 beside it. Two of those examples (nix-darwin's nix.settings and NixOS's configuration.nix) also used substituters / trusted-public-keys instead of extra-substituters / extra-trusted-public-keys; the bare form replaces Nix's default list instead of merging into it, the same misconfiguration troubleshooting.mdx already documents, so it's fixed alongside the key addition rather than shipped a second time. The signing-keys page's new paragraph adds its own nix.conf line and nix.settings block with the real floxhub-1 value, instead of sending the reader to the install page for it. The install page stays linked for the full example, which also covers the flox-cache-public-1 binary-cache key. The floxhub-1 value is verified verbatim against rootfs/common/etc/nix/flox.conf in flox/flox-installers.

Be suspicious of the floxhub-1 key value itself — it appears nowhere else in flox/docs, so nothing else in this repo cross-checks it against flox-installers. concepts/cuda-catalog-and-cache.mdx also lists flox-cache-public-1, but for trusting Flox's CUDA build cache, not for installing FloxHub-published packages, so it's untouched here.

Further work

• Deferred: a shared Mintlify snippet for the key list. MDX code fences are literal, so a snippet couldn't substitute per-block variables, and the eight blocks touched here use five different syntaxes (.conf, .ini, flake nixConfig, NixOS/nix-darwin nix.settings) that share no common template. A cheaper drift guard — a CI grep asserting floxhub-1 appears next to every flox-cache-public-1 — would need its own ticket.
• customer/signing-keys.mdx:121 changes nix.settings.trusted-public-keys to nix.settings.extra-trusted-public-keys in the pre-existing "NixOS, nix-darwin, or home-manager" example, the same extra- fix applied to the install and troubleshooting pages. It isn't required to fix the floxhub-1 gap this PR is about — drop that hunk if it's out of scope for this ticket.

🤖 Generated with Claude Code

---

Via Forge (implementation-worker) • d44c191

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
flox	🟢 Ready	View Preview	Sep 25, 2026, 7:24 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[flox-forge-agent]

Implementation handoff note

Judgment calls this implementation made that reading the diff or exercising the feature will not surface. Each one names what it was responsive to and what happens if nobody answers.

Decisions exercising the code will not reveal

• my-package in the quoted error example is an arbitrary placeholder for the error's {0} slot — the message text around it is verified against cli/flox-rust-sdk/src/providers/buildenv.rs; the name itself is not. Default: stays unless a reviewer wants different wording.
• Left concepts/cuda-catalog-and-cache.mdx's flox-cache-public-1 line untouched — that page trusts Flox's CUDA build cache, a different concern from the floxhub-1 signing key here; the diff never names the file. Default: out of scope unless that cache also serves floxhub-1-signed packages.

Taken on trust

• The #generic-nix and #trust-a-public-key-to-install-published-artifacts anchors resolve — assumed from Mintlify's heading-to-slug convention, not confirmed by rendering; mint broken-links only caught unrelated pre-existing RSS links. Check by running mint dev and clicking both links.

As of 33fec51. This note records what the implementation run believed at that commit; later commits on the branch can overtake it, and it is not updated to follow them.

---

Via Forge (implementation-worker) • d44c191