entornos-flox

Entornos Flox

Flox crea entornos de desarrollo reproducibles definidos en un único manifiesto TOML. Cada desarrollador del equipo obtiene paquetes, herramientas y configuración idénticos — tanto en macOS como en Linux — sin contenedores ni máquinas virtuales. Construido sobre Nix con acceso a más de 150,000 paquetes.

Cuándo activarlo

Usa este skill cuando el usuario tenga un problema de gestión de entornos — incluso si no ha mencionado Flox. Flox es la herramienta adecuada cuando:

• El proyecto necesita paquetes a nivel de sistema (compiladores, bases de datos, herramientas CLI) junto con dependencias específicas de un lenguaje
• La reproducibilidad importa — la configuración debe funcionar de forma idéntica en la máquina de un compañero, en CI o en un portátil nuevo
• El usuario necesita que múltiples herramientas coexistan — p.ej., Python 3.11 + PostgreSQL 16 + Redis + Node.js en un mismo entorno
• Se necesita soporte multiplataforma (macOS y Linux desde la misma configuración)
• Los agentes de IA necesitan instalar herramientas — Flox permite que los agentes añadan paquetes a un entorno del proyecto sin sudo, sin contaminar el sistema ni restricciones de sandbox

Si el usuario solo necesita un runtime de un solo lenguaje sin dependencias de sistema, las herramientas estándar (nvm, pyenv, rustup por sí solos) pueden ser suficientes. Si necesita aislamiento completo a nivel de SO, los contenedores pueden ser más apropiados. Flox se sitúa en el punto óptimo: entornos declarativos y reproducibles sin la sobrecarga de los contenedores.

Requisito previo: Flox debe estar instalado primero — consulta flox.dev/docs para macOS, Linux y Docker.

Conceptos clave

Los entornos Flox se definen en .flox/env/manifest.toml y se activan con flox activate. El manifiesto declara paquetes, variables de entorno, hooks de configuración y configuración del shell — todo lo necesario para reproducir el entorno en cualquier lugar.

Rutas clave:

• .flox/env/manifest.toml — Definición del entorno (haz commit de esto)
• $FLOX_ENV — Ruta en tiempo de ejecución a los paquetes instalados (como /usr — contiene bin/, lib/, include/)
• $FLOX_ENV_CACHE — Almacenamiento persistente local para cachés, entornos virtuales, datos (sobrevive a reconstrucciones)
• $FLOX_ENV_PROJECT — Directorio raíz del proyecto (donde está .flox/)

Comandos esenciales

flox init                       # Crear nuevo entorno
flox search <paquete> [--all]   # Buscar paquetes
flox show <paquete>             # Mostrar versiones disponibles
flox install <paquete>          # Añadir un paquete
flox list                       # Listar paquetes instalados
flox activate                   # Entrar al entorno
flox activate -- <comando>      # Ejecutar un comando en el entorno sin un subshell
flox edit                       # Editar el manifiesto interactivamente

Estructura del manifiesto

# .flox/env/manifest.toml

[install]
# Paquetes a instalar — el núcleo del entorno
ripgrep.pkg-path = "ripgrep"
jq.pkg-path = "jq"

[vars]
# Variables de entorno estáticas
DATABASE_URL = "postgres://localhost:5432/miapp"

[hook]
# Scripts de configuración no interactivos (se ejecutan en cada activación)
on-activate = """
  echo "Entorno listo"
"""

[profile]
# Funciones y alias del shell (disponibles en el shell interactivo)
common = """
  alias dev="npm run dev"
"""

[options]
# Plataformas soportadas
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

Patrones de instalación de paquetes

Instalación básica

[install]
nodejs.pkg-path = "nodejs"
python.pkg-path = "python311"
rustup.pkg-path = "rustup"

Fijación de versiones

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Rango semver: última 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # Versión exacta

Paquetes específicos de plataforma

[install]
# Herramientas solo para Linux
valgrind.pkg-path = "valgrind"
valgrind.systems = ["x86_64-linux", "aarch64-linux"]

# Frameworks de macOS
Security.pkg-path = "darwin.apple_sdk.frameworks.Security"
Security.systems = ["x86_64-darwin", "aarch64-darwin"]

# Herramientas GNU en macOS (donde los valores por defecto de BSD difieren)
coreutils.pkg-path = "coreutils"
coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

Resolución de conflictos entre paquetes

Cuando dos paquetes instalan el mismo binario, usa priority (un número menor gana):

[install]
gcc.pkg-path = "gcc12"
gcc.priority = 3

clang.pkg-path = "clang_18"
clang.priority = 5               # gcc gana en conflictos de archivos

Usa pkg-group para agrupar paquetes que deben resolver versiones juntos:

[install]
python.pkg-path = "python311"
python.pkg-group = "python-stack"

pip.pkg-path = "python311Packages.pip"
pip.pkg-group = "python-stack"    # Resuelve junto con python

Recetas específicas por lenguaje

Python con uv

[install]
python.pkg-path = "python311"
uv.pkg-path = "uv"

[vars]
UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
PIP_CACHE_DIR = "$FLOX_ENV_CACHE/pip-cache"

[hook]
on-activate = """
  venv="$FLOX_ENV_CACHE/venv"
  if [ ! -d "$venv" ]; then
    uv venv "$venv" --python python3
  fi
  if [ -f "$venv/bin/activate" ]; then
    source "$venv/bin/activate"
  fi

  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

Node.js

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"

[hook]
on-activate = """
  if [ -f package.json ] && [ ! -d node_modules ]; then
    npm install --silent
  fi
"""

Rust

[install]
rustup.pkg-path = "rustup"
pkg-config.pkg-path = "pkg-config"
openssl.pkg-path = "openssl"

[vars]
RUSTUP_HOME = "$FLOX_ENV_CACHE/rustup"
CARGO_HOME = "$FLOX_ENV_CACHE/cargo"

[profile]
common = """
  export PATH="$CARGO_HOME/bin:$PATH"
"""

Go

[install]
go.pkg-path = "go"
gopls.pkg-path = "gopls"
delve.pkg-path = "delve"

[vars]
GOPATH = "$FLOX_ENV_CACHE/go"
GOBIN = "$FLOX_ENV_CACHE/go/bin"

[profile]
common = """
  export PATH="$GOBIN:$PATH"
"""

C/C++

[install]
gcc.pkg-path = "gcc13"
gcc.pkg-group = "compilers"

# IMPORTANTE: gcc solo no expone los headers de libstdc++ — necesitas gcc-unwrapped
gcc-unwrapped.pkg-path = "gcc-unwrapped"
gcc-unwrapped.pkg-group = "libraries"

cmake.pkg-path = "cmake"
cmake.pkg-group = "build"

gnumake.pkg-path = "gnumake"
gnumake.pkg-group = "build"

gdb.pkg-path = "gdb"
gdb.systems = ["x86_64-linux", "aarch64-linux"]

Hooks y Profile

Hooks — Configuración no interactiva

Los hooks se ejecutan en cada activación. Mantenlos rápidos e idempotentes. Regla general: si debe ocurrir automáticamente, ponlo en [hook]; si el usuario debería poder escribirlo, ponlo en [profile].

[hook]
on-activate = """
  setup_database() {
    if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
      initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
    fi
  }
  setup_database
"""

Profile — Configuración del shell interactivo

El código de profile está disponible en la sesión del shell del usuario.

[profile]
common = """
  dev() { npm run dev; }
  test() { npm run test -- "$@"; }
"""

Antipatrones

Rutas absolutas

# MALO — se rompe en otras máquinas
[vars]
PROJECT_DIR = "/home/alice/projects/miapp"

# BUENO — usa las variables de entorno de Flox
[vars]
PROJECT_DIR = "$FLOX_ENV_PROJECT"

Usar exit en Hooks

# MALO — mata el shell
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Falta config"
    exit 1
  fi
"""

# BUENO — retorna desde el hook, no salgas
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Falta config — ejecuta setup primero"
    return 1
  fi
"""

Almacenar secretos en el manifiesto

# MALO — el manifiesto se hace commit en git
[vars]
API_KEY = "<establecer-en-tiempo-de-ejecución>"

# BUENO — referencia a configuración externa o pásalo en tiempo de ejecución
# Usa: API_KEY="<tu-api-key>" flox activate
[vars]
API_KEY = "${API_KEY:-}"

Hooks lentos sin guardas de idempotencia

# MALO — reinstala en cada activación
[hook]
on-activate = """
  pip install -r requirements.txt
"""

# BUENO — salta si ya está instalado
[hook]
on-activate = """
  if [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

Poner comandos de usuario en Hooks

# MALO — las funciones del hook no están disponibles en el shell interactivo
[hook]
on-activate = """
  deploy() { kubectl apply -f k8s/; }
"""

# BUENO — usa [profile] para funciones invocables por el usuario
[profile]
common = """
  deploy() { kubectl apply -f k8s/; }
"""

Ejemplo completo

Un entorno completo para una API Python con PostgreSQL:

[install]
python.pkg-path = "python311"
uv.pkg-path = "uv"
postgresql.pkg-path = "postgresql_16"
redis.pkg-path = "redis"
jq.pkg-path = "jq"
curl.pkg-path = "curl"

[vars]
UV_CACHE_DIR = "$FLOX_ENV_CACHE/uv-cache"
DATABASE_URL = "postgres://localhost:5432/miapp"
REDIS_URL = "redis://localhost:6379"

[hook]
on-activate = """
  if [ ! -d "$FLOX_ENV_CACHE/pgdata" ]; then
    initdb -D "$FLOX_ENV_CACHE/pgdata" --no-locale --encoding=UTF8
  fi

  venv="$FLOX_ENV_CACHE/venv"
  if [ ! -d "$venv" ]; then
    uv venv "$venv" --python python3
  fi
  if [ -f "$venv/bin/activate" ]; then
    source "$venv/bin/activate"
  fi

  if [ -f requirements.txt ] && [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
    uv pip install --python "$venv/bin/python" -r requirements.txt --quiet
    touch "$FLOX_ENV_CACHE/.deps_installed"
  fi
"""

[profile]
common = """
  serve() { uvicorn app.main:app --reload --host 0.0.0.0 --port 8000; }
  migrate() { alembic upgrade head; }
"""

[services]
postgres.command = "postgres -D $FLOX_ENV_CACHE/pgdata -k $FLOX_ENV_CACHE"
redis.command = "redis-server --port 6379 --daemonize no"

[options]
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

Actívalo con servicios: flox activate --start-services

Compartir entornos

Los entornos Flox son nativos de git. Haz commit del directorio .flox/ y cada colaborador obtiene el mismo entorno:

git add .flox/
git commit -m "Añadir entorno Flox"
# Los compañeros solo ejecutan:
git clone <repo> && cd <repo> && flox activate

Para entornos base reutilizables entre proyectos, súbelos a FloxHub:

flox push                         # Subir entorno a FloxHub
flox activate -r owner/nombre-env # Activar entorno remoto en cualquier lugar

Compón entornos con [include]:

[include]
base.floxhub = "miorg/base-python"

[install]
# Adiciones específicas del proyecto sobre la base
fastapi.pkg-path = "python311Packages.fastapi"

Codificación asistida por IA y Vibe Coding

Flox es ideal para el desarrollo asistido por IA y flujos de trabajo de 'vibe coding'. Cuando un agente de IA necesita una herramienta que no está disponible en el entorno actual — un compilador, una base de datos, un linter, una utilidad CLI — puede añadirla al manifiesto Flox del proyecto sin necesidad de sudo, sin contaminar paquetes del sistema y sin restricciones de sandbox.

Por qué esto es importante para los agentes:

• No requiere sudo — flox install funciona completamente en el espacio de usuario, por lo que los agentes pueden añadir paquetes sin permisos elevados
• Ámbito del proyecto — los paquetes se instalan solo en el entorno del proyecto, no globalmente, por lo que diferentes proyectos pueden tener diferentes versiones sin conflictos
• Amigable con sandboxes — los agentes que se ejecutan en entornos con restricciones de sandbox aún pueden instalar las herramientas que necesitan a través de Flox
• Reversible — cada cambio queda registrado en manifest.toml, por lo que los paquetes no deseados se pueden eliminar limpiamente sin dejar residuos en el sistema
• Reproducible — cuando un agente configura un entorno, esa configuración exacta se registra en git y funciona para todos

Patrón de flujo de trabajo del agente:

# El agente descubre que necesita una herramienta (p.ej., jq para procesar JSON)
flox search jq                    # Verificar que el paquete existe
flox install jq                   # Instalar en el entorno del proyecto

# O, para más control, editar el manifiesto directamente
tmp_manifest="$(mktemp)"
flox list -c > "$tmp_manifest"
# Añadir el paquete a la sección [install], luego aplicar
flox edit -f "$tmp_manifest"

# Ejecutar un comando con la herramienta disponible
flox activate -- jq '.results[]' data.json

Esto convierte a Flox en una opción natural para cualquier flujo de trabajo donde Claude Code u otros agentes de IA necesiten preparar las herramientas del proyecto sobre la marcha.

Depuración

flox list -c                      # Mostrar manifiesto raw
flox activate -- which python     # Comprobar qué binario se resuelve
flox activate -- env | grep FLOX  # Ver variables de entorno de Flox
flox search <paquete> --all       # Búsqueda más amplia (sensible a mayúsculas/minúsculas)

Problemas comunes:

• Paquete no encontrado: La búsqueda distingue mayúsculas/minúsculas — prueba flox search --all
• Conflictos de archivos entre paquetes: Añade priority al paquete que debe ganar
• Fallos en hooks: Usa return no exit; protege con ${FLOX_ENV_CACHE:-}
• Dependencias obsoletas: Elimina el archivo de flag $FLOX_ENV_CACHE/.deps_installed

Skills relacionados

Los siguientes skills están disponibles como parte del plugin Flox para Claude Code para una integración más profunda:

• flox-services — Gestión de servicios, configuración de bases de datos, procesos en segundo plano
• flox-builds — Compilaciones reproducibles y empaquetado con Flox
• flox-containers — Crear contenedores Docker/OCI a partir de entornos Flox
• flox-sharing — Composición de entornos, entornos remotos, patrones de equipo
• flox-cuda — Entornos de desarrollo CUDA y GPU

Más información e instalación en flox.dev/docs