nixfredFLOXFIELD GUIDE · BY NIX UNOFFICIAL
ObjectionsSecurityFAQGlossaryBlog digestWhat is FloxNix 101ArchitectureAgentsEnterpriseUnofficial. Not affiliated with Flox.
EXECUTE / SCENARIOS AND REFERENCE ARCHITECTURES

Scenarios and reference architectures

Six situations a customer brings to a call, each with who is asking, what to ask, the Flox answer with exact steps, a success measure and the honest risk. Every step comes from the Flox docs, case studies or blog; where the sources stop, the page says so and flags it [verify].

This page is drawn from https://flox.dev/case-studies/how-fellow-ai-ships-faster-with-flox/, https://flox.dev/case-studies/how-resolve-ai-eliminated-works-on-my-machine/, https://flox.dev/blog/code-and-its-runtime-should-travel-together/, https://flox.dev/blog/reproducible-flox-environments-for-the-first-and-the-last-mile-of-ai/, https://flox.dev/blog/deploying-hardened-flox-nvidia-cuda-stacks-in-minutes-not-hours/, https://flox.dev/docs/tutorials/ci-cd, https://flox.dev/docs/imageless-kubernetes/intro, https://flox.dev/blog/kubernetes-uncontained-explained-unlocking-faster-more-reproducible-deployments-on-k8s/, https://flox.dev/blog/cves-are-now-being-exploited-much-faster-than-you-can-respond/, https://flox.dev/blog/achieving-rapid-cve-remediation-in-an-era-of-escalating-vulnerabilities/, https://flox.dev/deterministic-agents/ and https://flox.dev/docs/llms.txt. A CoreWeave-specific source was not in the corpus, so none is cited here.

How to use these

  • Run the questions first, the steps second. Each scenario ends with a success measure the customer agrees to before any trial, the same habit as the POC criteria page.
  • Command syntax is in the CLI cheat sheet page and in https://flox.dev/docs/man/flox.
  • Case-study numbers are the vendor’s own write-ups. Quote them as such.

Scenario A: 50 developers and a stale setup doc

Situation. Engineers onboard from “a mix of docs, scripts, package managers, and tribal knowledge” (https://flox.dev/case-studies/how-resolve-ai-eliminated-works-on-my-machine/). The README is out of date: the Flox blog says “README files and static documentation aren’t an authoritative definition of what a repo needs to build and run” (https://flox.dev/blog/code-and-its-runtime-should-travel-together/).

Who asks. A platform or developer-experience lead, or an engineering manager whose new hires lose their first week.

Ask.

  • How many distinct local setups exist today, and who updates the setup doc?
  • When a build breaks, how often is the first question whether it is the code or someone’s machine?
  • Are you on Docker for local dev, and what does it cost on laptops? Fellow cited slow startup times and performance issues on older MacBooks (https://flox.dev/case-studies/how-fellow-ai-ships-faster-with-flox/).

Flox answer.

  1. Pick one repo. In it, run flox init, then flox install for the toolchain, so .flox/ holds a manifest and lockfile (https://flox.dev/docs/man/flox-init, https://flox.dev/docs/man/flox-install).
  2. Commit .flox/. The blog says both live in .flox/ “and are versioned with Git” (https://flox.dev/blog/code-and-its-runtime-should-travel-together/).
  3. New contributors clone and run flox activate. To onboard existing repos faster, the floxify skill detects runtimes, services and build tools and writes a manifest, so flox activate becomes “the only setup command a new developer needs” (https://flox.dev/docs/llms.txt).
  4. Roll out in phases. Fellow “started out small, giving engineers in local dev the option to use Flox. Most did” (https://flox.dev/case-studies/how-fellow-ai-ships-faster-with-flox/). Resolve AI began with engineers open to trying it (https://flox.dev/case-studies/how-resolve-ai-eliminated-works-on-my-machine/).
  5. Dependency changes go through pull requests with the code, and git revert restores code and runtime together (https://flox.dev/blog/code-and-its-runtime-should-travel-together/).

Success measure. Time from clone to first passing build for a new hire, and the count of “works on my machine” threads per month. Fellow’s CTO reported that “Once all the dev machines could run the same Flox environments, this rarely happened” (https://flox.dev/case-studies/how-fellow-ai-ships-faster-with-flox/). Resolve AI saw the question turn into “are you using Flox?” (https://flox.dev/case-studies/how-resolve-ai-eliminated-works-on-my-machine/).

Honest risk. Flox “didn’t completely solve” drift everywhere; the write-up says it did “essentially eliminate drift in local development” (https://flox.dev/case-studies/how-fellow-ai-ships-faster-with-flox/). Resolve AI notes some engineers avoided automatic activation with direnv when rebases triggered extra setup time (https://flox.dev/case-studies/how-resolve-ai-eliminated-works-on-my-machine/). Adoption was social more than technical, so budget for champions.

Scenario B: ML team, CUDA and PyTorch the same on laptop and cluster

Situation. Researchers prototype on MacBooks, experiment on NVIDIA DGX and train on Slurm. Teams grapple with a unit-of-change problem: containers give side-by-side CUDA stacks “at the cost of building and maintaining massive, multi-gigabyte container images” (https://flox.dev/blog/deploying-hardened-flox-nvidia-cuda-stacks-in-minutes-not-hours/).

Who asks. ML platform or MLOps lead, or a capital-markets quant-infrastructure group.

Ask.

Flox answer.

  1. Define one PyTorch environment with per-system entries: torch.systems = ["x86_64-linux", "aarch64-linux"] for the CUDA build and a separate macOS entry for Apple’s MPS build (https://flox.dev/blog/reproducible-flox-environments-for-the-first-and-the-last-mile-of-ai/).
  2. Add a CUDA environment from the Flox Catalog with flox-cuda/cudaPackages.* pkg-paths, limited to Linux systems, so Mac users do not get it (same post).
  3. Compose them with [include] in a project environment, so conflicts surface “during resolution, not later at runtime” (same post).
  4. On Slurm, a job script calls flox activate -d "$SLURM_SUBMIT_DIR", or nodes run flox activate -r <owner>/<name> (same post).
  5. Promote by reference: the unit of promotion becomes “an atomic reference (a Git commit or a specific generation of a FloxHub environment)” (same post).
flowchart LR
  A[Laptop MPS<br/>prototype] --> E[One pinned<br/>Flox environment]
  B[DGX<br/>experiment] --> E
  C[Slurm<br/>training] --> E
  E --> D[Eval]
  D --> F[Kubernetes<br/>serving]
Whiteboard diagram (rendered from the source mermaid)

Success measure. Same pinned versions on every stage (diff the manifest.lock files), plus time to swap a version. The CUDA post reports a prebuilt CUDA PyTorch wheel from the Flox Catalog takes 1m and 11s versus more than 65 minutes to build from source on a 32-core machine (https://flox.dev/blog/deploying-hardened-flox-nvidia-cuda-stacks-in-minutes-not-hours/). Re-measure on the customer’s hardware.

Honest risk. “If you’re on a CUDA system, make sure you’ve got a fast Internet connection and 10 gigabytes of disk space” (https://flox.dev/blog/reproducible-flox-environments-for-the-first-and-the-last-mile-of-ai/). The blog’s examples use a community FloxHub owner for the composed stack; check the customer’s own catalog coverage and driver support before promising GPU parity [verify].

Scenario C: platform team wants CI parity with laptops

Situation. CI installs tools differently from laptops, so failures appear only in the pipeline.

Who asks. A platform engineer who owns pipelines, or a release manager.

Ask. Which tools does CI install, from where, and is any version unpinned? Who owns the CI credentials?

Flox answer.

  1. Commit the environment. The docs say “the exact same set of software can be used for local development and a CI/CD pipeline” (https://flox.dev/docs/tutorials/ci-cd).
  2. GitHub Actions: flox/install-flox-action@v2, then flox/activate-action@v1 with command: npm run build (https://flox.dev/docs/tutorials/ci-cd). CircleCI has a Flox Orb with flox/install and flox/activate steps (same page). GitLab uses an image with Flox preinstalled (same page).
  3. A pipeline using only an environment committed to the repo “needs no credentials at all”; for FloxHub environments, private catalogs or publishing, give the pipeline a service account and put its token in FLOX_FLOXHUB_TOKEN (same page).
  4. A read-only service account “can pull environments and install packages but cannot push or publish” (same page).
  5. In scripts, use flox activate -d <dir> -c '<command>', not bare flox activate (https://flox.dev/docs/llms.txt).

Success measure. Count of failures that reproduce in CI but not locally, before and after. Also compare the lockfile hash CI used with the one a developer has.

Honest risk. The docs call their examples “an example project; yours will probably look a little different” (https://flox.dev/docs/tutorials/ci-cd). Service accounts depend on the organization setup (https://flox.dev/docs/concepts/service-accounts); confirm plan availability with Flox [verify].

Scenario D: Kubernetes team tired of huge images (imageless Kubernetes)

Situation. Every small code change means rebuilding and propagating layers everywhere, as Fellow’s CTO put it (https://flox.dev/case-studies/how-fellow-ai-ships-faster-with-flox/). The Flox Kubernetes page speaks of ending “multi-gigabyte round trips” (https://flox.dev/kubernetes). A specific 10 GB figure is not in the sources [verify with the customer’s own image sizes].

Who asks. A Kubernetes platform lead, or an MLOps owner with large GPU images.

Ask.

  • How big are your images, how long is a rebuild-push-pull loop, and how much registry storage and egress do you pay for?
  • Which clusters are EKS or self-managed, and can you add a runtime class? Docs cover Amazon EKS and self-managed clusters (https://flox.dev/docs/imageless-kubernetes/intro).

Flox answer.

  1. Push the environment to FloxHub; it “must be an environment that has been pushed to FloxHub” (https://flox.dev/docs/imageless-kubernetes/intro).
  2. In the pod, set the annotation flox.dev/environment, runtimeClassName: flox, a stub image flox/empty:1.0.0 and your command (same page). The stub is a 49-byte image (https://flox.dev/blog/kubernetes-uncontained-explained-unlocking-faster-more-reproducible-deployments-on-k8s/).
  3. To add a package: flox install -r myorg/myenv somepackage, then flox push -r myorg/myenv, then redeploy the pod. The docs say “No need to rebuild an image.” (same intro page).
  4. Roll back by switching generation with flox generations rollback -r myorg/myenv (https://flox.dev/docs/man/flox-generations-rollback).
flowchart TD
  H[FloxHub<br/>environment] --> S[containerd shim<br/>on the node]
  P[Pod spec<br/>runtimeClassName flox] --> S
  S --> C[Node local<br/>hash addressed cache]
  C --> R[Container runs<br/>inside the environment]
Whiteboard diagram (rendered from the source mermaid)

Success measure. Time from merged change to a running pod, bytes pulled per rollout, and registry storage freed. Fellow named memory overhead and image churn as the pain (https://flox.dev/case-studies/how-fellow-ai-ships-faster-with-flox/).

Honest risk. Fellow had not shipped this: it “is starting to introduce Flox into its CI and deployment tooling” and was “exploring” imageless pods (https://flox.dev/case-studies/how-fellow-ai-ships-faster-with-flox/). Nodes need the Flox shim installed and labeled. Admission control and scanners built around image digests need rework: the blog says admission can gate on the environment annotation and SBOM (https://flox.dev/blog/kubernetes-uncontained-explained-unlocking-faster-more-reproducible-deployments-on-k8s/). Treat that as a design item to test, not a given [verify].

Scenario E: security team asks which environments contain this CVE

Situation. A CVE drops, and the team scans every image and host. The Flox post: “CVE triage scales with the number of artifacts, images, hosts, or runtime environments you run” (https://flox.dev/blog/achieving-rapid-cve-remediation-in-an-era-of-escalating-vulnerabilities/).

Who asks. A security engineer, vulnerability-management lead, or compliance owner in a regulated firm.

Ask.

  • Where is your system of record for packages, including transitive ones and base images?
  • How long from advisory to a list of affected workloads, and who does it by hand?

Flox answer.

  1. Every environment resolves to a lockfile and closure. Environments with the same closure can be treated as one unit; the post’s example is “If 500 environments collapse to 50” unique sets, analysis runs 50 times, not 500 (https://flox.dev/blog/achieving-rapid-cve-remediation-in-an-era-of-escalating-vulnerabilities/).
  2. FloxHub generates SBOMs for packages and complete environments; index them against vulnerability data, then query which graphs contain the affected package (same post). The post also says “The Flox SBOM is a mathematical proof, not an inference.” (https://flox.dev/blog/cves-are-now-being-exploited-much-faster-than-you-can-respond/).
  3. On Kubernetes, annotate pods with the environment hash and kubectl get pods -A -o json | jq on that annotation lists namespaces, pods and nodes. The post shows this with a blocklist at admission via Kyverno, Gatekeeper or OPA (https://flox.dev/blog/cves-are-now-being-exploited-much-faster-than-you-can-respond/).
  4. Fix: edit manifest.toml, re-lock, rebuild and publish a new generation, then confirm the vulnerable output is gone from the new graph (https://flox.dev/blog/achieving-rapid-cve-remediation-in-an-era-of-escalating-vulnerabilities/).

Success measure. Time to a verified list of affected environments, and the ratio of unique closures to environments.

Honest risk. The post says plainly this “isn’t O(1)”: teams still test behavior, coordinate rollout and promote the replacement (https://flox.dev/blog/achieving-rapid-cve-remediation-in-an-era-of-escalating-vulnerabilities/). Only what is captured in Flox and Nix environments gets this treatment; software outside them does not. The annotation key in the blog’s YAML and its query differ (floxenv/hash and flox.dev/hash), so confirm the real key [verify]. Scanner integration is a design item, not a button.

Scenario F: adopting AI coding agents that need the same toolchain

Situation. Agents run on laptops, sandboxes and CI. Flox’s agents page says, “When the toolchain, services, and pinned versions drift between a laptop, a sandbox, and CI, the agent ends up debugging the substrate instead of doing the work” (https://flox.dev/deterministic-agents/).

Who asks. An engineering director rolling out Claude Code, Codex or Cursor, or a platform team supporting sandboxes.

Ask.

  • Which harnesses and sandboxes are in play, and how do agents install tools today?
  • What stops an agent from changing the host or pulling an unsanctioned dependency?

Flox answer.

  1. Pin the toolchain once in the manifest, then run the agent inside it: flox activate -- claude (https://flox.dev/deterministic-agents/).
  2. Give the agent the safe forms: flox activate -d <dir> -c '<command>' or -- <command>, never bare flox activate; install with flox install; verify names with flox search and flox show (https://flox.dev/docs/llms.txt).
  3. Install the skills: claude plugin marketplace add flox/flox-skills then claude plugin install flox@flox-skills, or npx skills add flox/flox-skills for other agents (https://flox.dev/docs/llms.txt).
  4. Layer under existing isolation: Flox “does not replace the tools your agents run in, it slots underneath them” (https://flox.dev/deterministic-agents/).
  5. Agents work without touching $HOME: setup “without modifying your $HOME or making global changes of any kind” (https://flox.dev/blog/next-level-agentic-development-with-flox/).

Success measure. Share of agent sessions that fail on setup rather than on the task, and tokens spent on dependency debugging. Both need baselining on the customer’s repos.

Honest risk. An environment fixes the toolchain, not the agent’s behavior. A bare flox activate can hang a non-interactive harness (https://flox.dev/docs/llms.txt). Agent setup times in the blog (usually under a minute) are vendor observations, not benchmarks (https://flox.dev/blog/next-level-agentic-development-with-flox/).

Close-out checklist

  • Success measure written down and agreed per scenario
  • One repo or one cluster chosen as the trial, not the whole company
  • Auth plan: who gets accounts, service accounts for CI (https://flox.dev/docs/tutorials/ci-cd)
  • Every number quoted marked as vendor-reported or measured by you
  • Open [verify] items sent to Flox for confirmation

← Competitor questions and answers · POC and demo scripts →