# flox-environments

> A Claude Code skill from Affaan M's everything-claude-code repo for declarative reproducible dev environments via Flox — a Nix-based environment manager with 150K+ packages, single TOML manifest at .flox/env/manifest.toml, cross-platform (macOS / Linux) parity, version pinning, hooks, and project-scoped install without sudo. Especially useful for AI agents that need tools without system pollution.

**Use case**: Declare a reproducible dev environment (compilers + databases + native libs) in one TOML manifest

**Canonical URL**: https://agentcookbooks.com/skills/flox-environments/

**Topics**: claude-code, skills, devenv

**Trigger phrases**: "set up Flox for this project", "reproducible Python + Postgres environment", "fix works on my machine with Flox"

**Source**: [Affaan M](https://github.com/affaan-m/everything-claude-code/tree/main/skills/flox-environments)

**License**: MIT

---

## What it does

`flox-environments` is the reproducible-dev-environment skill in [Affaan M's everything-claude-code](https://github.com/affaan-m/everything-claude-code) — see [skills/flox-environments](https://github.com/affaan-m/everything-claude-code/tree/main/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](https://github.com/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](https://github.com/affaan-m/everything-claude-code/tree/main/skills/flox-environments) — 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.