flox-environments

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• set up Flox for this project
• reproducible Python + Postgres environment
• fix works on my machine with Flox

What it does

flox-environments is the reproducible-dev-environment skill in Affaan M’s everything-claude-code — see skills/flox-environments. It covers Flox — a Nix-based declarative environment manager that defines a development environment in a single TOML manifest (.flox/env/manifest.toml). One activation command produces an identical environment on macOS or Linux with system-level packages, language runtimes, native libraries, and local services side by side. The skill’s wedge for AI work is that agents can install tools into a project-scoped environment without sudo, system pollution, or sandbox restrictions.

Manifest structure has five sections: [install] for packages with pkg-path + optional version pin (nodejs.pkg-path = "nodejs" + nodejs.version = "^20.0"), [vars] for static env vars, [hook] for setup scripts run on every activation, [profile] for shell-only aliases and functions, [options] for supported platforms array. Three runtime path variables — $FLOX_ENV (installed packages root, like /usr), $FLOX_ENV_CACHE (persistent local storage that survives rebuilds — venvs, caches, data), $FLOX_ENV_PROJECT (project root).

Essential commands: flox init creates the environment, flox search <package> finds packages across the 150K+ index, flox show <package> lists versions, flox install <package> adds a package, flox activate enters the environment, flox activate -- <cmd> runs a one-off command without a subshell. The activation model is opt-in — entering the directory doesn’t auto-activate; you call flox activate explicitly. Cross-platform support is per-package (systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]) so the manifest spans architectures.

When to use it

• Project needs system-level packages (compilers, databases, native libs like openssl / libvips / BLAS / LAPACK) alongside language deps
• Reproducibility matters — the setup must work identically on a teammate’s machine, in CI, or on a fresh laptop
• Multiple tools need to coexist — Python 3.11 + PostgreSQL 16 + Redis + Node in one environment
• Cross-platform support is needed (macOS and Linux from the same config)
• AI agents need to install tools into a project-scoped environment without sudo or system pollution
• Onboarding new developers with flox activate as the single setup command

When not to reach for it:

• Project needs only a single language runtime with no system deps — standard tooling (nvm, pyenv, rustup) is lighter
• Full OS-level isolation is required — containers are the right fit there
• Production deployment environments — Flox is a dev environment, not a deployment target
• Quick one-off scripts — overhead exceeds value

Install

From affaan-m/everything-claude-code at skills/flox-environments/. Drop the folder into ~/.claude/skills/flox-environments/. The skill is markdown — runtime requires Flox itself installed first (see flox.dev/docs/install-flox/install/ for macOS, Linux, and Docker installs). The manifest at .flox/env/manifest.toml gets committed; the resolution file alongside it pins exact package versions for reproducibility.

What a session looks like

1. Initialize the environment. flox init in the project root creates .flox/env/manifest.toml.
2. Add the needed packages. flox install python311 postgresql nodejs ripgrep jq adds each to the [install] section. Version pins go in via flox edit if needed.
3. Add env vars + hooks. [vars] for static config (DATABASE_URL, etc.). [hook] on-activate for setup scripts that must run on every activation (start a local Postgres, restore a Python venv from $FLOX_ENV_CACHE).
4. Set supported systems. [options] systems = ["aarch64-darwin", "x86_64-linux"] covers the M-series macOS developer plus the Linux CI runner.
5. Activate. flox activate drops the operator into the environment with $FLOX_ENV populated and the env vars set. flox activate -- npm install runs a one-off without a subshell.
6. Commit the manifest. .flox/env/manifest.toml + resolution file goes into git. Teammate clones, runs flox activate, gets the identical environment.
7. Agent-driven additions. An agent that needs pandoc or imagemagick can run flox install pandoc imagemagick — project-scoped, no sudo, no ~/.local pollution.

The discipline that makes it work: commit the manifest. Without that, “Flox works on my machine” reduces to the same problem Flox is solving. The committed .flox/env/manifest.toml is the contract — every team member, every CI run, every agent gets the same package set.

Receipts

TODO — to be filled in from a real session. Once Flox has been used to set up a real cross-platform project, this section will capture: which package version pin actually broke first (the canonical one is nodejs 18 vs. 20 across team members), how the $FLOX_ENV_CACHE persistence behaved across rebuilds (Python venvs are the most common test case), whether the on-activate hook landed cleanly on first run or needed debugging through flox activate --trace, and the actual time saved on new-developer onboarding vs. the previous README-driven setup.

Source and attribution

From Affaan M’s everything-claude-code — an MIT-licensed skill collection covering harness construction, agent ops, video, payments, and platform-specific patterns.

License: MIT.

Quoting the AI-agent rationale verbatim: “Flox lets agents install tools into a project-scoped environment without sudo, system pollution, or sandbox restrictions.” That’s the wedge that makes Flox AI-shaped — agents that need additional tooling don’t end up trying to write to /usr/local or asking for sudo; they call flox install and the manifest absorbs the change.