flox-environments

Ambientes Flox

O Flox cria ambientes de desenvolvimento reproduzíveis definidos em um único manifesto TOML. Cada desenvolvedor na equipe obtém pacotes, ferramentas e configurações idênticas — tanto no macOS quanto no Linux — sem contêineres ou VMs. Construído sobre o Nix com acesso a mais de 150.000 pacotes.

Quando Ativar

Use este skill quando o usuário tiver um problema de gerenciamento de ambiente — mesmo que ele não tenha mencionado o Flox. O Flox é a ferramenta certa quando:

• O projeto precisa de pacotes de nível de sistema (compiladores, bancos de dados, ferramentas CLI) ao lado de dependências específicas de linguagem
• A reprodutibilidade é importante — a configuração deve funcionar de forma idêntica na máquina de um colega, no CI ou em um laptop novo
• O usuário precisa que múltiplas ferramentas coexistam — ex.: Python 3.11 + PostgreSQL 16 + Redis + Node.js em um ambiente
• Suporte multiplataforma é necessário (macOS e Linux a partir da mesma configuração)
• Agentes de IA precisam instalar ferramentas — o Flox permite que agentes adicionem pacotes a um ambiente com escopo de projeto sem sudo, poluição do sistema ou restrições de sandbox

Se o usuário precisa apenas de um runtime de linguagem única sem dependências de sistema, as ferramentas padrão (nvm, pyenv, rustup isolados) podem ser suficientes. Se for necessário isolamento completo a nível de SO, contêineres podem ser mais apropriados. O Flox está no ponto ideal: ambientes declarativos e reproduzíveis sem a sobrecarga de contêineres.

Pré-requisito: O Flox deve ser instalado primeiro — veja flox.dev/docs para macOS, Linux e Docker.

Conceitos Principais

Os ambientes Flox são definidos em .flox/env/manifest.toml e ativados com flox activate. O manifesto declara pacotes, variáveis de ambiente, hooks de configuração e configuração do shell — tudo o que é necessário para reproduzir o ambiente em qualquer lugar.

Caminhos importantes:

• .flox/env/manifest.toml — Definição do ambiente (commite isto)
• $FLOX_ENV — Caminho em tempo de execução para os pacotes instalados (como /usr — contém bin/, lib/, include/)
• $FLOX_ENV_CACHE — Armazenamento local persistente para caches, venvs, dados (sobrevive a reconstruções)
• $FLOX_ENV_PROJECT — Diretório raiz do projeto (onde .flox/ está localizado)

Comandos Essenciais

flox init                       # Criar novo ambiente
flox search <package> [--all]   # Procurar pacotes
flox show <package>             # Mostrar versões disponíveis
flox install <package>          # Adicionar um pacote
flox list                       # Listar pacotes instalados
flox activate                   # Entrar no ambiente
flox activate -- <cmd>          # Executar um comando no ambiente sem um subshell
flox edit                       # Editar manifesto interativamente

Estrutura do Manifesto

# .flox/env/manifest.toml

[install]
# Pacotes para instalar — o núcleo do ambiente
ripgrep.pkg-path = "ripgrep"
jq.pkg-path = "jq"

[vars]
# Variáveis de ambiente estáticas
DATABASE_URL = "postgres://localhost:5432/myapp"

[hook]
# Scripts de configuração não interativos (executados a cada ativação)
on-activate = """
  echo "Ambiente pronto"
"""

[profile]
# Funções e aliases do shell (disponíveis no shell interativo)
common = """
  alias dev="npm run dev"
"""

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

Padrões de Instalação de Pacotes

Instalação Básica

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

Fixação de Versão

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Faixa Semver: último 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # Versão exata

Pacotes Específicos por Plataforma

[install]
# Ferramentas somente Linux
valgrind.pkg-path = "valgrind"
valgrind.systems = ["x86_64-linux", "aarch64-linux"]

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

# Ferramentas GNU no macOS (onde os padrões BSD diferem)
coreutils.pkg-path = "coreutils"
coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

Resolvendo Conflitos de Pacotes

Quando dois pacotes instalam o mesmo binário, use priority (número menor vence):

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

clang.pkg-path = "clang_18"
clang.priority = 5               # gcc vence conflitos de arquivo

Use pkg-group para agrupar pacotes que devem resolver versões juntos:

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

pip.pkg-path = "python311Packages.pip"
pip.pkg-group = "python-stack"    # Resolve junto com python

Receitas Específicas por Linguagem

Python com 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: apenas gcc não expõe cabeçalhos libstdc++ — você precisa de 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 e Profile

Hooks — Configuração Não Interativa

Os hooks são executados em cada ativação. Mantenha-os rápidos e idempotentes. Regra prática: se deve acontecer automaticamente, coloque em [hook]; se o usuário deve poder digitar, coloque em [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 — Configuração do Shell Interativo

O código do profile fica disponível na sessão do shell do usuário.

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

Antipadrões

Caminhos Absolutos

# RUIM — quebra em outras máquinas
[vars]
PROJECT_DIR = "/home/alice/projects/myapp"

# BOM — use variáveis de ambiente do Flox
[vars]
PROJECT_DIR = "$FLOX_ENV_PROJECT"

Usar exit em Hooks

# RUIM — mata o shell
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Config ausente"
    exit 1
  fi
"""

# BOM — retorne do hook, não saia
[hook]
on-activate = """
  if [ ! -f config.json ]; então
    echo "Config ausente — execute setup primeiro"
    return 1
  fi
"""

Armazenar Segredos no Manifesto

# RUIM — manifesto é commitado no git
[vars]
API_KEY = "<definido-em-tempo-de-execução>"

# BOM — referencie configuração externa ou passe em tempo de execução
# Use: API_KEY="<sua-api-key>" flox activate
[vars]
API_KEY = "${API_KEY:-}"

Hooks Lentos Sem Proteções de Idempotência

# RUIM — reinstala a cada ativação
[hook]
on-activate = """
  pip install -r requirements.txt
"""

# BOM — pula se já 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
"""

Colocar Comandos de Usuário em Hooks

# RUIM — funções de hook não estão disponíveis no shell interativo
[hook]
on-activate = """
  deploy() { kubectl apply -f k8s/; }
"""

# BOM — use [profile] para funções invocáveis pelo usuário
[profile]
common = """
  deploy() { kubectl apply -f k8s/; }
"""

Exemplo de Stack Completa

Um ambiente completo para uma API Python com 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"]

Ative com serviços: flox activate --start-services

Compartilhamento de Ambientes

Os ambientes Flox são nativos do git. Commite o diretório .flox/ e cada colaborador obtém o mesmo ambiente:

git add .flox/
git commit -m "Adicionar ambiente Flox"
# Colegas apenas executam:
git clone <repo> && cd <repo> && flox activate

Para ambientes base reutilizáveis entre projetos, envie para o FloxHub:

flox push                         # Enviar ambiente para o FloxHub
flox activate -r owner/env-name   # Ativar ambiente remoto em qualquer lugar

Componha ambientes com [include]:

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

[install]
# Adições específicas do projeto sobre a base
fastapi.pkg-path = "python311Packages.fastapi"

Codificação Assistida por IA e Vibe Coding

O Flox é ideal para desenvolvimento assistido por IA e fluxos de trabalho de vibe coding. Quando um agente de IA precisa de uma ferramenta que não está disponível no ambiente atual — um compilador, um banco de dados, um linter, um utilitário CLI — ele pode adicioná-la ao manifesto Flox do projeto sem exigir acesso sudo, poluir os pacotes do sistema ou encontrar restrições de sandbox.

Por que isso é importante para agentes:

• Nenhum sudo necessário — flox install funciona inteiramente no espaço do usuário, então os agentes podem adicionar pacotes sem permissões elevadas
• Escopo de projeto — os pacotes são instalados apenas no ambiente do projeto, não globalmente, permitindo que projetos diferentes tenham versões diferentes sem conflito
• Compatível com sandbox — agentes executando em ambientes com sandbox ou restritos ainda podem instalar as ferramentas de que precisam através do Flox
• Reversível — cada mudança é capturada em manifest.toml, então pacotes indesejados podem ser removidos de forma limpa sem resíduo no sistema
• Reproduzível — quando um agente configura um ambiente, essa configuração exata é commitada no git e funciona para todos

Padrão de fluxo de trabalho do agente:

# Agente descobre que precisa de uma ferramenta (ex.: jq para processamento JSON)
flox search jq                    # Verificar se o pacote existe
flox install jq                   # Instalar no ambiente do projeto

# Ou para mais controle, editar o manifesto diretamente
tmp_manifest="$(mktemp)"
flox list -c > "$tmp_manifest"
# Adicionar o pacote à seção [install] e depois aplicar
flox edit -f "$tmp_manifest"

# Executar um comando com a ferramenta disponível
flox activate -- jq '.results[]' data.json

Isso torna o Flox uma escolha natural para qualquer fluxo de trabalho onde o Claude Code ou outros agentes de IA precisam preparar as ferramentas do projeto dinamicamente.

Depuração

flox list -c                      # Mostrar manifesto bruto
flox activate -- which python     # Verificar qual binário resolve
flox activate -- env | grep FLOX  # Ver variáveis de ambiente do Flox
flox search <package> --all       # Busca mais ampla de pacote (sensível a maiúsculas/minúsculas)

Problemas comuns:

• Pacote não encontrado: A busca diferencia maiúsculas/minúsculas — tente flox search --all
• Conflitos de arquivos entre pacotes: Adicione priority ao pacote que deve vencer
• Falhas em hooks: Use return não exit; proteja com ${FLOX_ENV_CACHE:-}
• Dependências desatualizadas: Exclua o arquivo de sinalização $FLOX_ENV_CACHE/.deps_installed

Skills Relacionados

Os seguintes skills estão disponíveis como parte do plugin Flox para Claude Code para integração mais profunda:

• flox-services — Gerenciamento de serviços, configuração de banco de dados, processos em segundo plano
• flox-builds — Builds e empacotamento reproduzíveis com Flox
• flox-containers — Criar contêineres Docker/OCI a partir de ambientes Flox
• flox-sharing — Composição de ambientes, ambientes remotos, padrões de equipe
• flox-cuda — Ambientes de desenvolvimento CUDA e GPU

Saiba mais e instale em flox.dev/docs