ambientes-flox

Ambientes Flox

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

Quando Ativar

Use esta habilidade quando o usuário tiver um problema de gerenciamento de ambiente — mesmo que 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) junto com 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 várias ferramentas coexistam — por exemplo, Python 3.11 + PostgreSQL 16 + Redis + Node.js em um único 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 precisar apenas de um runtime de linguagem único sem dependências de sistema, ferramentas padrão (nvm, pyenv, rustup sozinhos) podem ser suficientes. Se precisar de isolamento total em nível de SO, contêineres podem ser mais apropriados. O Flox fica 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 Centrais

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 principais:

• .flox/env/manifest.toml — Definição do ambiente (commite isto)
• $FLOX_ENV — Caminho de runtime para 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 <pacote> [--all]    # Procurar pacotes
flox show <pacote>             # Mostrar versões disponíveis
flox install <pacote>          # 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 a 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 do shell e aliases (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: última 20.x

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

Pacotes Específicos de Plataforma

[install]
# Ferramentas apenas para 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 de 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

Hooks são executados a 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 -- "$@"; }
"""

Anti-Padrõ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 ]; then
    echo "Config ausente — execute a configuração primeiro"
    return 1
  fi
"""

Armazenar Segredos no Manifesto

# RUIM — manifesto é commitado no git
[vars]
API_KEY = "<definir-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 Guardas de Idempotência

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

# BOM — pula se já estiver 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 do 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 Completo

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 pacotes do sistema ou enfrentar 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 agentes podem adicionar pacotes sem permissões elevadas
• Escopo de projeto — pacotes são instalados apenas no ambiente do projeto, não globalmente, então diferentes projetos podem ter versões diferentes sem conflito
• Amigável a 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íduos 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, edite o manifesto diretamente
tmp_manifest="$(mktemp)"
flox list -c > "$tmp_manifest"
# Adicione o pacote à seção [install], depois aplique
flox edit -f "$tmp_manifest"

# Execute 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 Claude Code ou outros agentes de IA precisam preparar ferramentas de projeto em tempo real.

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 <pacote> --all       # Busca mais ampla de pacotes (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 arquivo 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

Habilidades Relacionadas

As seguintes habilidades estão disponíveis como parte do plugin Flox 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 reproduzíveis e empacotamento com Flox
• flox-containers — Criação de 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