From 33fec51f76152aa23071abb54f8124bddbd06cc5 Mon Sep 17 00:00:00 2001 From: Forge Date: Fri, 25 Sep 2026 19:19:22 +0000 Subject: [PATCH 1/2] docs(install): trust floxhub-1 alongside the Nix cache key Packages published to FloxHub-hosted catalogs are signed with floxhub-1, which the Flox installer trusts by default. A system that got Nix through some other path (nix profile install, nix-darwin, NixOS) never receives that key, so installing a published package fails as untrusted with no doc pointing at the fix. Add floxhub-1 alongside the existing flox-cache-public-1 key in every Nix trust-configuration example on the generic-install page and in troubleshooting, and add a short section to the signing-keys page naming the default key and linking installers of Nix straight to the fix. While touching these blocks, also fix nix-darwin's nix.settings and NixOS's configuration.nix examples, which set substituters and trusted-public-keys instead of their extra- counterparts; the bare form replaces Nix's defaults instead of merging into them, the same defect install-flox/troubleshooting.mdx already documents as a common misconfiguration. Refs: CLI-233 Forge-Agent: implementation-worker (d44c191) Co-Authored-By: Claude Sonnet 5 --- customer/signing-keys.mdx | 13 +++++++++++-- install-flox/install.mdx | 26 ++++++++++++++++++-------- install-flox/troubleshooting.mdx | 3 ++- 3 files changed, 31 insertions(+), 11 deletions(-) diff --git a/customer/signing-keys.mdx b/customer/signing-keys.mdx index 8cf2151..348d411 100644 --- a/customer/signing-keys.mdx +++ b/customer/signing-keys.mdx @@ -4,7 +4,16 @@ description: "Create and use signing keys to sign built artifacts" --- In order to upload a package it must be signed, and in order to install a package published to a Flox Catalog you must configure your system to trust the public key used to sign the package. -By default, packages are signed with a key that's included with the Flox installer, so Flox is configured to be able to install user-published packages out of the box. +By default, packages published to FloxHub-hosted catalogs are signed with the `floxhub-1` key, which ships with the Flox installer, so Flox is configured to be able to install user-published packages out of the box. + +If you installed Flox with Nix instead of the Flox installer — for example with `nix profile install`, or as part of a nix-darwin or NixOS configuration — your system doesn't have the `floxhub-1` key, and installing a package published to a FloxHub-hosted catalog fails with: + +```text +Package 'my-package' is not signed by a trusted key. +See https://flox.dev/docs/customer/signing-keys/ for more information. +``` + +To fix this, add `floxhub-1` to your Nix configuration's trusted public keys, the same way you would [trust any other public key](#trust-a-public-key-to-install-published-artifacts) — see the [generic Nix install instructions](/install-flox/install#generic-nix) for the exact key value and the config syntax for your setup. However, if you're providing your own Catalog Store, then you must @@ -91,7 +100,7 @@ For systems whose configuration is managed with Nix, you need to add the public For NixOS, `nix-darwin`, and `home-manager` the configuration option is the same: ```nix -nix.settings.trusted-public-keys = [ +nix.settings.extra-trusted-public-keys = [ "" ]; ``` diff --git a/install-flox/install.mdx b/install-flox/install.mdx index 1300728..fa24b4f 100644 --- a/install-flox/install.mdx +++ b/install-flox/install.mdx @@ -402,7 +402,7 @@ description: "How to install or upgrade the Flox CLI" ```bash title="/etc/nix/nix.conf" extra-trusted-substituters = https://cache.flox.dev - extra-trusted-public-keys = flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs= + extra-trusted-public-keys = flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs= floxhub-1:0QOAlcobcEvq1mqEf4qAYCaWnTTOXpyoRv/PmqfSixM= ``` Then restart the `nix-daemon`, if applicable: @@ -463,7 +463,7 @@ description: "How to install or upgrade the Flox CLI" ```bash title="/etc/nix/nix.conf" extra-trusted-substituters = https://cache.flox.dev - extra-trusted-public-keys = flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs= + extra-trusted-public-keys = flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs= floxhub-1:0QOAlcobcEvq1mqEf4qAYCaWnTTOXpyoRv/PmqfSixM= ``` Or, to your flake configuration by using the `nixConfig` attribute. @@ -473,7 +473,10 @@ description: "How to install or upgrade the Flox CLI" { nixConfig = { extra-trusted-substituters = ["https://cache.flox.dev"]; - extra-trusted-public-keys = ["flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs="]; + extra-trusted-public-keys = [ + "flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs=" + "floxhub-1:0QOAlcobcEvq1mqEf4qAYCaWnTTOXpyoRv/PmqfSixM=" + ]; }; } ``` @@ -487,7 +490,10 @@ description: "How to install or upgrade the Flox CLI" nixConfig = { extra-trusted-substituters = ["https://cache.flox.dev"]; - extra-trusted-public-keys = ["flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs="]; + extra-trusted-public-keys = [ + "flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs=" + "floxhub-1:0QOAlcobcEvq1mqEf4qAYCaWnTTOXpyoRv/PmqfSixM=" + ]; }; inputs = { @@ -513,11 +519,12 @@ description: "How to install or upgrade the Flox CLI" nix.settings = { experimental-features = "nix-command flakes"; - substituters = [ + extra-substituters = [ "https://cache.flox.dev" ]; - trusted-public-keys = [ + extra-trusted-public-keys = [ "flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs=" + "floxhub-1:0QOAlcobcEvq1mqEf4qAYCaWnTTOXpyoRv/PmqfSixM=" ]; }; @@ -542,8 +549,11 @@ description: "How to install or upgrade the Flox CLI" On NixOS, configure `/etc/nixos/configuration.nix` to add the lines: ```text title="/etc/nixos/configuration.nix" - nix.settings.trusted-substituters = [ "https://cache.flox.dev" ]; - nix.settings.trusted-public-keys = [ "flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs=" ]; + nix.settings.extra-trusted-substituters = [ "https://cache.flox.dev" ]; + nix.settings.extra-trusted-public-keys = [ + "flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs=" + "floxhub-1:0QOAlcobcEvq1mqEf4qAYCaWnTTOXpyoRv/PmqfSixM=" + ]; ``` ... and then invoke: diff --git a/install-flox/troubleshooting.mdx b/install-flox/troubleshooting.mdx index 6adf378..919b112 100644 --- a/install-flox/troubleshooting.mdx +++ b/install-flox/troubleshooting.mdx @@ -377,6 +377,7 @@ nix.settings = { extra-substituters = [ "https://cache.flox.dev" ]; extra-trusted-public-keys = [ "flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs=" + "floxhub-1:0QOAlcobcEvq1mqEf4qAYCaWnTTOXpyoRv/PmqfSixM=" ]; }; ``` @@ -385,7 +386,7 @@ Or directly in `/etc/nix/nix.conf`: ```ini extra-substituters = https://cache.flox.dev -extra-trusted-public-keys = flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs= +extra-trusted-public-keys = flox-cache-public-1:7F4OyH7ZCnFhcze3fJdfyXYLQw/aV7GEed86nQ7IsOs= floxhub-1:0QOAlcobcEvq1mqEf4qAYCaWnTTOXpyoRv/PmqfSixM= ``` Verify the change took effect: From 0bf26a084089e6bf1a7680e0bf942a962a4fa673 Mon Sep 17 00:00:00 2001 From: Forge Date: Fri, 25 Sep 2026 19:24:46 +0000 Subject: [PATCH 2/2] docs(signing-keys): give the floxhub-1 fix inline, not just a link The prior paragraph pointed Nix-installed users at the generic-Nix install page for "the exact key value and the config syntax." That makes the fix two hops away from the error it explains. Show the nix.conf line and the NixOS/nix-darwin nix.settings block directly, with the real floxhub-1 key, and keep the generic-Nix page linked only as further reading (it also covers the flox cache-public key, which this page has no reason to duplicate). Refs: CLI-233 Forge-Agent: implementation-worker (d44c191) Co-Authored-By: Claude Sonnet 5 --- customer/signing-keys.mdx | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/customer/signing-keys.mdx b/customer/signing-keys.mdx index 348d411..f2e4544 100644 --- a/customer/signing-keys.mdx +++ b/customer/signing-keys.mdx @@ -13,7 +13,25 @@ Package 'my-package' is not signed by a trusted key. See https://flox.dev/docs/customer/signing-keys/ for more information. ``` -To fix this, add `floxhub-1` to your Nix configuration's trusted public keys, the same way you would [trust any other public key](#trust-a-public-key-to-install-published-artifacts) — see the [generic Nix install instructions](/install-flox/install#generic-nix) for the exact key value and the config syntax for your setup. +To fix this, add `floxhub-1` to your Nix configuration's trusted public keys, the same way you would [trust any other public key](#trust-a-public-key-to-install-published-artifacts). + +If you're using a standalone Nix or Flox-installed Nix setup, add `floxhub-1` to the `extra-trusted-public-keys` line in `/etc/nix/nix.conf` (append to an existing line rather than adding a second one): + +```text +extra-trusted-public-keys = floxhub-1:0QOAlcobcEvq1mqEf4qAYCaWnTTOXpyoRv/PmqfSixM= +``` + +Then [restart the Nix daemon](#add-a-new-trusted-key). + +If your system is managed by NixOS or nix-darwin, add it to `nix.settings` instead, then rebuild and switch into your configuration: + +```nix +nix.settings.extra-trusted-public-keys = [ + "floxhub-1:0QOAlcobcEvq1mqEf4qAYCaWnTTOXpyoRv/PmqfSixM=" +]; +``` + +See the [generic Nix install instructions](/install-flox/install#generic-nix) for the full configuration examples, including the Flox binary cache key. However, if you're providing your own Catalog Store, then you must