> ## Documentation Index
> Fetch the complete documentation index at: https://flox.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Which Flox commands need a free account, what stays open, and how to keep CI running.

Starting **Tuesday, October 20, 2026**, Flox CLI commands that resolve packages
will require authentication with a free Flox account. The change arrives with
Flox 1.19.0 and applies to [older versions](#older-flox-versions) too.

## What's changing

Several Flox commands have always run through Flox cloud services for search,
indexing, package resolution, and environment operations. Beginning October
20, every command that resolves packages against the Flox catalog will
require authentication. A command resolves packages when:

* [`flox install`](/docs/man/flox-install) adds a package from the catalog.
* You run [`flox upgrade`](/docs/man/flox-upgrade), including
  `flox upgrade --dry-run`.
* You run [`flox run`](/docs/man/flox-run).
* A command has to lock the environment because `manifest.lock` is missing,
  or because you added or changed a catalog package or a system. This covers
  [`flox activate`](/docs/man/flox-activate), [`flox edit`](/docs/man/flox-edit),
  [`flox list`](/docs/man/flox-list), [`flox uninstall`](/docs/man/flox-uninstall),
  `flox services`, [`flox build`](/docs/man/flox-build),
  [`flox develop`](/docs/man/flox-develop),
  [`flox containerize`](/docs/man/flox-containerize) and
  [`flox include upgrade`](/docs/man/flox-include-upgrade).

Changing `[vars]`, `[hook]`, `[profile]` or `[services]` locks the environment
without contacting the catalog, so it needs no sign-in. Installing a flake
reference or a Nix store path doesn't use the catalog either.

[`flox init`](/docs/man/flox-init) creates an environment without a sign-in. In a
project where Flox detects Node.js, Python or Go, its package suggestions need
one.

<Accordion title="Do I need to do anything?">
  Probably not, and if you do it's one command. Find the row closest to how you
  use Flox.

  | What you're doing | Sign in? | What to do |
  | - | - | - |
  | Activating an environment whose lockfile is current | No | Nothing |
  | Looking up packages with `flox search` or `flox show` | No | Nothing |
  | Adding, upgrading, or changing packages in your own environment | Yes | Run `flox auth login` once |
  | CI that activates an environment with a committed, current lockfile | No | Nothing |
  | CI that installs or upgrades packages each time | Yes | Give it a [token](#ci-and-automation) |
</Accordion>

## What stays the same

[`flox activate`](/docs/man/flox-activate) does not require authentication for an
environment that already has a current lockfile. If your daily workflow or CI pipeline
simply activates an existing environment that relies on public packages, nothing
changes for you.

[`flox search`](/docs/man/flox-search) and [`flox show`](/docs/man/flox-show) stay open
too, so browsing the catalog needs no account. So does pulling a public
environment with [`flox pull`](/docs/man/flox-pull), and so does
[`flox build`](/docs/man/flox-build) when the environment's lockfile is current.

Private packages and environments continue to require authentication as they
do today, and so does [publishing](/docs/concepts/publishing). Nothing about those
changes.

## Why we're doing this

Flox has grown from an open source CLI into foundational infrastructure used
across developer machines, CI, build systems, and increasingly AI agents. As
usage has grown exponentially, so has our responsibility to operate the cloud
services behind Flox reliably and to keep improving them based on how they're
actually being used.

Requiring authentication for the commands that interact with those services
gives us a better foundation for understanding those workflows, operating the
service reliably, and investing in the parts of Flox people depend on most. It
also gives us better standards around abuse prevention.

We're intentionally keeping `flox activate` available without an account for
public environments. If you're consuming an environment someone else
maintains, you do not need to create an account just to use it.

To be clear: this is not a paywall. The free tier keeps the same capabilities
it has today. You'll need a free account for the commands above, not a paid
subscription.

## Signing in

FloxHub has made it easy to login. How you sign in depends on where you're
running Flox.

<Tabs>
  <Tab title="On your machine">
    Run [`flox auth login`](/docs/man/flox-auth) and follow the browser prompt. You
    can log in with an existing GitHub, Google, or GitLab account. If you don't
    have an account, the same flow creates one.

    ```bash theme={null}
    flox auth login
    ```

    You do this once per machine. Paid customers can also authenticate with
    their own SSO provider — see [Enterprise SSO](/docs/concepts/enterprise-sso).
  </Tab>

  <Tab title="No browser">
    Over SSH, inside a container, or anywhere a browser can't open, use a
    token instead. A
    [personal access token](/docs/concepts/personal-access-tokens) signs the CLI in
    as you. A [service account](/docs/concepts/service-accounts) token signs it in
    as your organization. The CLI reads either one from the same variable.

    ```bash theme={null}
    export FLOX_FLOXHUB_TOKEN=<your-token>
    ```
  </Tab>
</Tabs>

You can also sign in on the web at [hub.flox.dev](https://hub.flox.dev).

## CI and automation

Automation breaks quietly, so it's worth handling before anything else. Two
ways through:

* **Commit your lockfile.** A pipeline that activates an existing environment
  against a committed `manifest.lock` never calls the catalog, so there's no
  token to manage. You get reproducible builds and one less network dependency
  out of it, which is worth doing anyway.
* **Or give the pipeline a token.** Pipelines that run `flox install`,
  `flox upgrade`, or any of the other commands above do reach the catalog. So
  does `flox build` when the lockfile it's building against is out of date.
  Issue a token in FloxHub and set it as `FLOX_FLOXHUB_TOKEN` from your CI
  platform's secret store. The pipeline or agent then runs Flox commands
  without user interaction.

A [personal access token](/docs/concepts/personal-access-tokens) works on any
account, including a free personal one, and acts as you. A
[service account](/docs/concepts/service-accounts) token belongs to an organization
instead, so the pipeline keeps running after someone changes teams or leaves.
The CLI reads both from the same variable.

The [CI/CD tutorial](/docs/tutorials/ci-cd) covers setup on specific platforms.

<Warning>
  Service account and personal access tokens need **Flox CLI 1.14.0 or newer**.
  Older releases reject the token as invalid and clear it, so the pipeline
  fails as though it were never set. Check with `flox --version`, and see
  [installing Flox](/docs/install-flox/install) to upgrade. If the pipeline can't
  upgrade, commit its lockfile instead.
</Warning>

### GitHub Actions

On GitHub Actions, pass the token to
[`flox/install-flox-action`](https://github.com/flox/install-flox-action) as
`floxhub-token`. The action logs Flox in before it runs any other Flox command,
and logs out when the job ends.

```yaml title=".github/workflows/ci.yml" theme={null}
steps:
  - uses: "flox/install-flox-action@v2"
    with:
      floxhub-token: ${{ secrets.FLOXHUB_TOKEN }}
```

The `floxhub-token` input needs `install-flox-action` v2.7.0 or newer. The
`@v2` tag already includes it. If you pin an exact version or a commit, move
the pin forward.

## Older Flox versions

The Flox catalog enforces the requirement, so from October 20 it applies to
every Flox version, not only 1.19.0. Staying on an older release doesn't
postpone it. What you need depends on the version you run:

| Flox version | What you need |
| - | - |
| 1.14.0 and newer | Run `flox auth login`, or set a token in `FLOX_FLOXHUB_TOKEN` |
| 1.3.5 through 1.13 | Run `flox auth login`. Personal access tokens and service account tokens need 1.14.0 |
| Before 1.3.5 | [Upgrade](/docs/install-flox/install) first. These versions never send your login to the catalog, so they can't resolve packages even when you're logged in |

## FAQ

<AccordionGroup>
  <Accordion title="Do I have to pay for Flox now?">
    No. Flox has always had a free tier and we keep adding to it. You need a
    free account, not a paid subscription.
  </Accordion>

  <Accordion title="What happens to my CI pipelines?">
    If your pipeline uses one of the commands listed above, add a personal
    access token or a service account token to your CI secrets before
    October 20. Pipelines that only activate an existing environment against a
    committed, current lockfile carry on unchanged.
  </Accordion>

  <Accordion title="What's the exact cutoff date?">
    Tuesday, October 20, 2026, the day Flox 1.19.0 ships. The requirement
    applies to every Flox version from that date, so
    [older versions](#older-flox-versions) need a sign-in too.
  </Accordion>

  <Accordion title="What if I miss the deadline?">
    Commands that resolve packages fail with an error that tells you to run
    `flox auth login`. Run it, then run the command again. Signing up takes
    under a minute.
  </Accordion>

  <Accordion title="How do I turn off the login reminders?">
    When you aren't logged in, Flox reminds you to run `flox auth login`. To
    turn the reminder off:

    ```bash theme={null}
    flox config --set auth_notifications false
    ```

    Or set `FLOX_AUTH_NOTIFICATIONS=false` in the environment, which is usually
    easier in CI. Both need Flox 1.15.0 or newer. They silence the reminder
    only. A command that needs a sign-in still fails with an error until you
    log in.
  </Accordion>

  <Accordion title="Do you have an option that isn't public FloxHub?">
    Yes. FloxHub Enterprise runs on your own infrastructure. Email
    [hello@flox.dev](mailto:hello@flox.dev) for more information.
  </Accordion>

  <Accordion title="My question was not addressed here.">
    Ask in [Flox Community Slack](https://go.flox.dev/slack) or on
    [Flox Discourse](https://discourse.flox.dev/), or email [support@flox.dev](mailto:support@flox.dev).
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.