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ênticos — em macOS e Linux — sem contêineres ou VMs. Construído sobre 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) ao lado de dependências específicas da linguagem
• A reprodutibilidade importa — a configuração deve funcionar identicamente na máquina de um colega de equipe, em 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
• É necessário suporte multiplataforma (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 único runtime de linguagem sem dependências de sistema, ferramentas padrão (nvm, pyenv, rustup sozinhos) podem ser suficientes. Se eles precisarem de isolamento completo em nível de SO, contêineres podem ser mais apropriados. O Flox se encaixa perfeitamente: 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 chave:

• .flox/env/manifest.toml — Definição do ambiente (faça commit disso)
• $FLOX_ENV — Caminho de tempo de execução 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/ reside)

Comandos Essenciais

flox init                       # Create new environment
flox search <package> [--all]   # Search for packages
flox show <package>             # Show available versions
flox install <package>          # Add a package
flox list                       # List installed packages
flox activate                   # Enter environment
flox activate -- <cmd>          # Run a command in the environment without a subshell
flox edit                       # Edit manifest interactively

Estrutura do Manifesto

# .flox/env/manifest.toml

[install]
# Packages to install — the core of the environment
ripgrep.pkg-path = "ripgrep"
jq.pkg-path = "jq"

[vars]
# Static environment variables
DATABASE_URL = "postgres://localhost:5432/myapp"

[hook]
# Non-interactive setup scripts (run every activation)
on-activate = """
  echo "Environment ready"
"""

[profile]
# Shell functions and aliases (available in interactive shell)
common = """
  alias dev="npm run dev"
"""

[options]
# Supported platforms
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"          # Semver range: latest 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # Exact version

Pacotes Específicos de Plataforma

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

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

# GNU tools on macOS (where BSD defaults differ)
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 (menor número vence):

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

clang.pkg-path = "clang_18"
clang.priority = 5               # gcc wins file conflicts

Use pkg-group para agrupar pacotes cujas versões devem ser resolvidas juntas:

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

pip.pkg-path = "python311Packages.pip"

…