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. Está construido sobre Nix y ofrece acceso a más de 150,000 paquetes.

Cuándo Activar

Usa esta habilidad cuando el usuario tenga un problema de gestión de entornos — incluso si no han 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 del lenguaje
• La reproducibilidad importa — la configuración debe funcionar de manera idéntica en la máquina de un compañero, en CI o en un portátil nuevo
• El usuario necesita que varias herramientas coexistan — por ejemplo, Python 3.11 + PostgreSQL 16 + Redis + Node.js en un solo entorno
• Se necesita soporte multiplataforma (macOS y Linux desde la misma configuración)
• Los agentes de IA necesitan instalar herramientas — Flox permite a los agentes añadir paquetes a un entorno limitado al proyecto sin sudo, sin contaminar el sistema ni restricciones de sandbox

Si el usuario solo necesita un entorno de ejecución de un solo lenguaje sin dependencias de sistema, las herramientas estándar (nvm, pyenv, rustup solos) pueden ser suficientes. Si necesitan un aislamiento completo a nivel de sistema operativo, los contenedores podrían ser más adecuados. 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 (hay que subir esto al repositorio)
• $FLOX_ENV — Ruta en tiempo de ejecución a los paquetes instalados (como /usr — contiene bin/, lib/, include/)
• $FLOX_ENV_CACHE — Almacenamiento local persistente para cachés, entornos virtuales, datos (sobrevive a las reconstrucciones)
• $FLOX_ENV_PROJECT — Directorio raíz del proyecto (donde está .flox/)

Comandos Esenciales

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

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/myapp"

[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 compatibles
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 predeterminados 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 (el número más bajo gana):

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

clang.pkg-path = "clang_18"
clang.priority = 5               # gcc gana los 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 encabezados 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 Perfil

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
"""

Perfil — Configuración del Shell Interactivo

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

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

Anti-Patrones

Rutas Absolutas

# MALO — no funciona en otras máquinas
[vars]
PROJECT_DIR = "/home/alice/projects/myapp"

# 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 la configuración primero"
    return 1
  fi
"""

Almacenar Secretos en el Manifiesto

# MALO — el manifiesto se sube a git
[vars]
API_KEY = "<configurar-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 Protecciones de Idempotencia

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

# BUENO — omite 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 de una Aplicación

Un entorno completo para una API de 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/myapp"
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"]

Activar con servicios: flox activate --start-services

Compartir Entornos

Los entornos Flox son nativos de git. Sube el 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 el entorno a FloxHub
flox activate -r owner/env-name   # Activar entorno remoto desde cualquier lugar

Compón entornos con [include]:

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

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

Asistencia con IA y Codificación por Vibra

Flox es ideal para el desarrollo asistido por IA y los flujos de trabajo de codificación por vibra. 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 los paquetes del sistema ni tener restricciones de sandbox.

Por qué es importante para los agentes:

• No se requiere sudo — flox install funciona completamente en el espacio de usuario, por lo que los agentes pueden añadir paquetes sin permisos elevados
• Ámbito de proyecto — los paquetes se instalan solo en el entorno del proyecto, no de forma global, por lo que diferentes proyectos pueden tener diferentes versiones sin conflictos
• Amigable con sandboxes — los agentes que se ejecutan en entornos con sandbox o restringidos pueden seguir instalando las herramientas que necesitan a través de Flox
• Reversible — cada cambio se captura 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 sube a git y funciona para todos

Patrón de flujo de trabajo del agente:

# El agente descubre que necesita una herramienta (por ejemplo, jq para procesamiento 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 el manifiesto sin procesar
flox activate -- which python     # Verificar qué binario se resuelve
flox activate -- env | grep FLOX  # Ver las variables de entorno de Flox
flox search <package> --all       # Búsqueda de paquetes más amplia (distingue mayúsculas y minúsculas)

Problemas comunes:

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

Habilidades Relacionadas

Las siguientes habilidades 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 y empaquetado reproducibles 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

Aprende más e instala en flox.dev/docs