REFERENCE / FAQ QUICKFIRE

FAQ quickfire

One-line answers with a source for each, grouped by topic: install, manifest, catalog, FloxHub, CI, containers, Kubernetes, agents, pricing, security and platforms. If the answer is not here, the sources below are where to look next. Anything the sources do not settle is marked [verify].

Install

Question	Answer	Source
How do I install Flox?	`curl -fsSL https://get.flox.dev \| sh`. It picks the `.pkg` on macOS, the `.deb` on Debian and Ubuntu, the `.rpm` on Fedora and RHEL families.	https://flox.dev/docs/install-flox/install
Can I pin a version?	Yes: `FLOX_VERSION=<version>` pins exactly, `FLOX_CHANNEL=<channel>` picks a channel (default `stable`).	https://flox.dev/docs/install-flox/install
Does Flox phone home?	The CLI sends usage telemetry and error reports. `FLOX_DISABLE_METRICS=true` turns both off, but not the requests search and install need.	https://flox.dev/docs/concepts/data-collection
Does Flox upload my source?	No, except in packages you publish. Pushing an environment stores its manifest and lockfile on FloxHub.	https://flox.dev/docs/concepts/data-collection

Manifest and environments

Question	Answer	Source
What is an environment?	A shell with packages, environment variables and activation scripts, layered on top of your system.	https://flox.dev/docs/concepts/environments
How do I edit the manifest?	`flox edit` opens your editor and validates on save.	https://flox.dev/docs/concepts/environments
What is a `pkg-path`?	The package’s location in the catalog, such as `ripgrep` or `python310Packages.pip`.	https://flox.dev/docs/man/manifest.toml
What is `manifest.lock`?	A snapshot of the package versions and dependencies built and activated. Flox manages it.	https://flox.dev/docs/concepts/environments
Does a schema change break my manifest?	Since CLI 1.10.0 Flox detects incompatible changes and migrates the manifest for you.	https://flox.dev/docs/concepts/compatibility
Can I combine environments?	Yes, with `[include]`. Later entries and the composing manifest win, and nothing can be removed from a lower one.	https://flox.dev/docs/man/manifest.toml
`[hook]` or `[profile]`?	`on-activate` runs in bash and sets state. `[profile]` is sourced by your shell for aliases and prompts.	https://flox.dev/docs/man/manifest.toml
How do I run a database?	Define it under `[services]` with a `command`, then `flox services start` or `flox activate -s`.	https://flox.dev/docs/concepts/services, https://flox.dev/docs/man/flox-activate
Does `flox activate --` run profile scripts?	No: exec mode runs `hook.on-activate` but skips `profile.*`.	https://flox.dev/docs/concepts/activation
Can it activate on `cd`?	Yes: auto-activation is on by default once the Flox prompt hook is in your shell.	https://flox.dev/docs/concepts/auto-activation

Catalog and packages

Question	Answer	Source
What is the catalog?	“A Flox Catalog is a collection of package artifacts and associated metadata that can be consumed via a Flox Environment.”	https://flox.dev/docs/concepts/packages-and-catalog
How fresh is it?	Upstream nixpkgs changes land daily from `nixos-unstable`.	https://flox.dev/docs/concepts/packages-and-catalog
How many packages?	Marketing pages say 215,000+ [verify]: it is a marketing number, not a docs figure.	https://flox.dev/deterministic-agents/
Do I need an account to search?	No: `flox search` queries the catalog without a FloxHub account.	https://flox.dev/docs/man/flox-search
Which systems are covered?	`aarch64-darwin`, `x86_64-darwin`, `aarch64-linux` and `x86_64-linux`.	https://flox.dev/docs/tutorials/multi-arch-environments
What is a package group?	Packages in one group resolve against the same nixpkgs commit; groups may differ.	https://flox.dev/docs/concepts/package-groups
What does “constraints too tight” mean?	Pinned old versions of two packages cannot share one revision. Put one in its own `pkg-group`.	https://flox.dev/docs/concepts/package-groups
Can I run something once?	`flox run` runs a catalog command with no `flox init` or install.	https://flox.dev/docs/man/flox-run
Unfree or broken packages?	Flox tries to serve known good builds; `allow_unfree`, `allow_broken` and `allow_missing_builds` override those defaults.	https://flox.dev/docs/concepts/base-catalog
How do I publish my own?	`flox build`, then `flox publish <name>`. The repo must be git-tracked, clean, with a remote and the revision pushed.	https://flox.dev/docs/concepts/publishing
Are builds sandboxed?	Off by default. `sandbox = "pure"` isolates; on macOS pure builds still have network access.	https://flox.dev/docs/concepts/manifest-builds

FloxHub and teams

Question	Answer	Source
What is FloxHub?	A cloud service for sharing environments, at hub.flox.dev.	https://flox.dev/docs/concepts/floxhub
How do I share an environment?	`flox push` it; others `flox pull owner/name` or `flox activate -r owner/name`.	https://flox.dev/docs/concepts/environments
Can I undo a change?	Yes: `flox generations rollback` or `flox generations switch <number>`.	https://flox.dev/docs/concepts/generations
What roles exist in an org?	Owner, Writer and Reader.	https://flox.dev/docs/concepts/organizations
Is SSO available?	On Enterprise: any SAML or OIDC provider, including Okta, Entra ID and Google Workspace.	https://flox.dev/docs/concepts/enterprise-sso

CI

Question	Answer	Source
How does CI authenticate?	Put a service account token in `FLOX_FLOXHUB_TOKEN`. A repo-only environment needs no credentials.	https://flox.dev/docs/tutorials/ci-cd
What is a service account?	An org-owned identity with `flox_sat_` tokens, read-only or read and write. Needs CLI 1.14.0 or newer and an org.	https://flox.dev/docs/concepts/service-accounts
GitHub Actions?	`flox/install-flox-action`, plus `flox/activate-action` to run a command in the environment.	https://flox.dev/docs/tutorials/ci-cd
CircleCI or GitLab?	A Flox Orb exists for CircleCI; in GitLab use a masked CI/CD variable for the token.	https://flox.dev/docs/tutorials/ci-cd

Containers and Kubernetes

Question	Answer	Source
Can I get an image?	`flox containerize` exports an environment to a registry, a file or another process.	https://flox.dev/docs/man/flox-containerize
Does macOS work?	It needs a supported runtime, because a proxy container builds the image.	https://flox.dev/docs/man/flox-containerize
What runs in the image?	Interactive runs behave like `flox activate`; non-interactive runs like `flox activate --`.	https://flox.dev/docs/man/flox-containerize
What is imageless Kubernetes?	“Imageless Kubernetes is a new way to run Kubernetes backed by Flox environments rather than container images.”	https://flox.dev/docs/imageless-kubernetes/intro
How does a pod ask for it?	The `flox.dev/environment` annotation, `runtimeClassName: flox`, and the tiny `flox/empty:1.0.0` image.	https://flox.dev/docs/imageless-kubernetes/intro
What does it need?	A `containerd` shim on each node, and `containerd` 1.7 or newer.	https://flox.dev/docs/imageless-kubernetes/install/self-managed
EKS advice?	Use a new node group for it rather than the existing one.	https://flox.dev/docs/imageless-kubernetes/install/eks

Agents, pricing, security

Question	Answer	Source
How do I teach an agent Flox?	`/plugin marketplace add flox/flox-skills`, then `/plugin install flox@flox-skills` in Claude Code.	https://github.com/flox/flox-skills
What skills are inside?	`flox`, `floxify` and `flox-debug`.	https://github.com/flox/flox-skills
What does it cost?	Personal is free, Team is $20/seat/month, Enterprise is custom.	https://flox.dev/pricing/
What is free?	Unlimited public FloxHub envs, 3 private envs, 5 private packages.	https://flox.dev/pricing/
Certifications?	SOC 2 Type II and ISO/IEC 27001:2022.	https://flox.dev/compliance/
Are SBOMs supported?	The site says they are deterministic, derived from the store-path graph [verify]: marketing claim.	https://flox.dev/secure-software-by-construction/
Where do secrets go?	In a secret store, fetched just in time during activation, never hardcoded in the manifest.	https://flox.dev/docs/concepts/secrets-management
What about GPUs?	Pre-built CUDA packages come from the catalog and binary cache, with no extra configuration for Flox users.	https://flox.dev/docs/concepts/cuda-catalog-and-cache
Does it work across macOS and Linux?	“Use the same setup across macOS and Linux, on both x86 and Arm.”	https://flox.dev/docs/

← CLI cheat sheet · Glossary →