flox-environments

Flox Environments

Flox 能透過單一 TOML 清單檔建立可重現的開發環境。無論是在 macOS 還是 Linux 上，團隊中的每位開發者都能取得完全相同的套件、工具與設定，且無需依賴容器或虛擬機器。Flox 基於 Nix 建置，可存取超過 15 萬個套件。

When to Activate

當使用者遇到環境管理問題時，即可啟用此 Skill——即使他們並未直接提及 Flox。在以下情境中，Flox 是最佳工具：

• 專案除了程式語言專用依賴外，還需要系統級套件（如編譯器、資料庫、CLI 工具）
• 重視環境可重現性——設定需在團隊成員的電腦、CI 環境或全新筆電上完全一致地運作
• 使用者需要多種工具共存——例如在單一環境中同時使用 Python 3.11 + PostgreSQL 16 + Redis + Node.js
• 需要跨平台支援（透過同一套設定同時支援 macOS 與 Linux）
• AI Agent 需要安裝工具——Flox 讓 Agent 能在無需 sudo 權限、不污染系統且不受沙盒限制的情況下，將套件新增至專案層級的環境中

如果使用者只需要單一程式語言的執行環境且無系統相依需求，使用標準工具（如單純使用 nvm、pyenv、rustup）就已足夠。若需要完整的作業系統級隔離，容器可能更為合適。Flox 則正好契合中間的最佳需求：無容器開銷的宣告式、可重現環境。

前置條件： 必須先安裝 Flox——請參閱 flox.dev/docs 以取得 macOS、Linux 與 Docker 的安裝說明。

Core Concepts

Flox 環境定義於 .flox/env/manifest.toml 中，並透過 flox activate 啟用。清單檔宣告了套件、環境變數、setup hook 與 shell 設定——即在任何地方重現環境所需的全部內容。

關鍵路徑：

• .flox/env/manifest.toml — 環境定義檔（需版控 Commit）
• $FLOX_ENV — 已安裝套件的執行階段路徑（類似 /usr——包含 bin/、lib/、include/）
• $FLOX_ENV_CACHE — 快取、虛擬環境 (venv)、資料的持久化本機儲存空間（重新建置後依然保留）
• $FLOX_ENV_PROJECT — 專案根目錄（.flox/ 所在的目錄）

Essential Commands

flox init                       # 建立新環境
flox search <package> [--all]   # 搜尋套件
flox show <package>             # 顯示可用版本
flox install <package>          # 新增套件
flox list                       # 列出已安裝套件
flox activate                   # 進入環境
flox activate -- <cmd>          # 在環境中執行指令（不開啟次 Shell）
flox edit                       # 以互動方式編輯清單檔

Manifest Structure

# .flox/env/manifest.toml

[install]
# 要安裝的套件 — 環境的核心部分
ripgrep.pkg-path = "ripgrep"
jq.pkg-path = "jq"

[vars]
# 靜態環境變數
DATABASE_URL = "postgres://localhost:5432/myapp"

[hook]
# 非互動式設定腳本（每次啟用時執行）
on-activate = """
  echo "Environment ready"
"""

[profile]
# Shell 函式與別名（在互動式 Shell 中可用）
common = """
  alias dev="npm run dev"
"""

[options]
# 支援的平台
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

Package Installation Patterns

Basic Installation

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

Version Pinning

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Semver 範圍：最新的 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # 精確版本

Platform-Specific Packages

[install]
# 僅限 Linux 的工具
valgrind.pkg-path = "valgrind"
valgrind.systems = ["x86_64-linux", "aarch64-linux"]

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

# macOS 上的 GNU 工具（因 BSD 預設工具行為不同）
coreutils.pkg-path = "coreutils"
coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

Resolving Package Conflicts

當兩個套件安裝相同的執行檔時，使用 priority（數字越小優先權越高）：

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

clang.pkg-path = "clang_18"
clang.priority = 5               # 檔案衝突時由 gcc 勝出

使用 pkg-group 將需要一起解析版本的套件進行分組：

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

pip.pkg-path = "python311Packages.pip"
pip.pkg-group = "python-stack"    # 與 python 一起解析

Language-Specific Recipes

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

# 重要：僅安裝 gcc 不會提供 libstdc++ 標頭檔 — 你需要 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 and Profile

Hooks — 非互動式設定

Hook 會在每次環境啟用時執行。請確保其執行快速且具備冪等性 (idempotent)。經驗法則：如果應該自動發生，請放在 [hook]；如果使用者需要能手動輸入，請放在 [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 — 互動式 Shell 設定

Profile 中的程式碼可用於使用者的 Shell 工作階段。

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

Anti-Patterns

絕對路徑

# 錯誤 — 在其他電腦上會失效
[vars]
PROJECT_DIR = "/home/alice/projects/myapp"

# 正確 — 使用 Flox 環境變數
[vars]
PROJECT_DIR = "$FLOX_ENV_PROJECT"

在 Hook 中使用 exit

# 錯誤 — 會直接終止整個 Shell
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Missing config"
    exit 1
  fi
"""

# 正確 — 從 Hook 返回，不要結束 Shell
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Missing config — run setup first"
    return 1
  fi
"""

在清單檔中儲存機密資訊

# 錯誤 — 清單檔會 Commit 到 Git
[vars]
API_KEY = "<set-at-runtime>"

# 正確 — 引用外部設定或在執行階段傳入
# 用法：API_KEY="<your-api-key>" flox activate
[vars]
API_KEY = "${API_KEY:-}"

缺乏冪等性保護的慢速 Hook

# 錯誤 — 每次啟用時都重新安裝
[hook]
on-activate = """
  pip install -r requirements.txt
"""

# 正確 — 如果已安裝則跳過
[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
"""

將使用者指令放入 Hook

# 錯誤 — Hook 中的函式無法在互動式 Shell 中使用
[hook]
on-activate = """
  deploy() { kubectl apply -f k8s/; }
"""

# 正確 — 供使用者呼叫的函式請使用 [profile]
[profile]
common = """
  deploy() { kubectl apply -f k8s/; }
"""

Full-Stack Example

含有 PostgreSQL 的 Python API 完整環境設定：

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

搭配服務啟用：flox activate --start-services

Environment Sharing

Flox 環境具備 Git 原生特性。只需 Commit .flox/ 目錄，每位協作者就能取得相同的環境：

git add .flox/
git commit -m "Add Flox environment"
# 團隊成員只需執行：
git clone <repo> && cd <repo> && flox activate

若要在跨專案間共享基底環境，可推送到 FloxHub：

flox push                         # 推送環境至 FloxHub
flox activate -r owner/env-name   # 在任何地方啟用遠端環境

使用 [include] 組合環境：

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

[install]
# 基底環境之上的專案專用擴充套件
fastapi.pkg-path = "python311Packages.fastapi"

AI-Assisted and Vibe Coding

Flox 非常適合 AI 輔助開發與 vibe coding 工作流程。當 AI Agent 需要目前環境中未提供的工具時——例如編譯器、資料庫、linter 或 CLI 工具——它可以直接將工具新增至專案的 Flox 清單檔中，無需 sudo 權限、不會污染系統套件，也不會觸發沙盒限制。

為什麼這對 Agent 很有幫助：

• 無需 sudo 權限 — flox install 完全在使用者空間運作，因此 Agent 無需提升權限即可新增套件
• 專案作用域 — 套件僅安裝於專案環境中而非全域，因此不同專案可以擁有不同的版本且不會衝突
• 對沙盒友善 — 在沙盒或受限環境中執行的 Agent 仍可順利安裝所需的工具

<!-- truncated for translation batch; full body continues in source -->