flox-environments

Flox Environments

Flox は、単一の TOML マニフェストで定義された再現可能な開発環境を作成します。チームのすべての開発者が、macOS と Linux の両方で、コンテナや VM を使わずに同一のパッケージ、ツール、設定を利用できます。Nix をベースに、150,000 以上のパッケージにアクセスできます。

アクティベートするタイミング

ユーザーが環境管理の問題を抱えている場合（Flox について言及していなくても）、このスキルを使用してください。Flox は以下のような場合に適したツールです。

• プロジェクトが システムレベルのパッケージ（コンパイラ、データベース、CLI ツール）を言語固有の依存関係と共に必要とする場合
• 再現性が重要 である場合 — セットアップがチームメイトのマシン、CI、新しいラップトップで同じように動作する必要がある場合
• 複数のツールを 共存させる 必要がある場合 — 例：1 つの環境に Python 3.11 + PostgreSQL 16 + Redis + Node.js
• クロスプラットフォーム のサポートが必要な場合（同じ設定で macOS と Linux）
• AI エージェントがツールをインストールする 必要がある場合 — Flox を使用すると、エージェントは sudo、システムの汚染、サンドボックスの制限なしに、プロジェクトスコープの環境にパッケージを追加できます。

ユーザーがシステム依存関係のない単一の言語ランタイムのみを必要とする場合は、標準的なツール（nvm、pyenv、rustup など）で十分な場合があります。完全な OS レベルの分離が必要な場合は、コンテナの方が適切かもしれません。Flox は、コンテナのオーバーヘッドなしに、宣言的で再現可能な環境という絶妙なバランスを提供します。

前提条件: Flox がインストールされている必要があります。macOS、Linux、Docker のインストール手順については、flox.dev/docs を参照してください。

コアコンセプト

Flox 環境は .flox/env/manifest.toml で定義され、flox activate でアクティベートされます。マニフェストは、パッケージ、環境変数、セットアップフック、シェル設定を宣言します。これにより、環境をどこでも再現するために必要なすべての情報が提供されます。

主要なパス:

• .flox/env/manifest.toml — 環境定義（これをコミットします）
• $FLOX_ENV — インストールされたパッケージへのランタイムパス（/usr と同様 — bin/、lib/、include/ を含む）
• $FLOX_ENV_CACHE — キャッシュ、venv、データ用の永続的なローカルストレージ（再ビルド後も保持されます）
• $FLOX_ENV_PROJECT — プロジェクトルートディレクトリ（.flox/ がある場所）

必須コマンド

flox init                       # 新しい環境を作成
flox search <package> [--all]   # パッケージを検索
flox show <package>             # 利用可能なバージョンを表示
flox install <package>          # パッケージを追加
flox list                       # インストール済みパッケージを一覧表示
flox activate                   # 環境に入る
flox activate -- <cmd>          # サブシェルなしで環境内でコマンドを実行
flox edit                       # マニフェストをインタラクティブに編集

マニフェスト構造

# .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]
# シェル関数とエイリアス（インタラクティブシェルで使用可能）
common = """
  alias dev="npm run dev"
"""

[options]
# サポート対象プラットフォーム
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

パッケージインストールパターン

基本的なインストール

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

バージョン固定

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Semver 範囲: 最新の 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # 正確なバージョン

プラットフォーム固有のパッケージ

[install]
# Linux 専用ツール
valgrind.pkg-path = "valgrind"
valgrind.systems = ["x86_64-linux", "aarch64-linux"]

# macOS フレームワーク
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"]

パッケージの競合解決

2 つのパッケージが同じバイナリをインストールする場合は、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 と一緒に解決

言語別レシピ

Python（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"]

フックとプロファイル

フック — 非対話型セットアップ

フックはアクティベーションのたびに実行されます。高速で冪等性を保つようにしてください。経験則として、自動的に実行されるべきものは [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]
common = """
  dev() { npm run dev; }
  test() { npm run test -- "$@"; }
"""

アンチパターン

絶対パス

# 悪い例 — 他のマシンでは動作しない
[vars]
PROJECT_DIR = "/home/alice/projects/myapp"

# 良い例 — Flox 環境変数を使用する
[vars]
PROJECT_DIR = "$FLOX_ENV_PROJECT"

フック内での exit の使用

# 悪い例 — シェルが強制終了される
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Missing config"
    exit 1
  fi
"""

# 良い例 — exit ではなく return でフックから戻る
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Missing config — run setup first"
    return 1
  fi
"""

マニフェストに秘密情報を保存する

# 悪い例 — マニフェストは git にコミットされる
[vars]
API_KEY = "<set-at-runtime>"

# 良い例 — 外部設定を参照するか、実行時に渡す
# 使用: API_KEY="<your-api-key>" flox activate
[vars]
API_KEY = "${API_KEY:-}"

冪等性保証のない低速なフック

# 悪い例 — アクティベーションのたびに再インストールされる
[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]
on-activate = """
  deploy() { kubectl apply -f k8s/; }
"""

# 良い例 — ユーザーが呼び出せる関数は [profile] を使用する
[profile]
common = """
  deploy() { kubectl apply -f k8s/; }
"""

フルスタックの例

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

環境の共有

Flox 環境は git ネイティブです。.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 支援と Vibe Coding

Flox は AI を活用した開発や Vibe Coding のワークフローに最適です。AI エージェントが現在の環境で利用できないツール（コンパイラ、データベース、リンター、CLI ユーティリティなど）を必要とする場合、sudo アクセス、システムパッケージの汚染、サンドボックスの制限なしに、プロジェクトの Flox マニフェストに追加できます。

エージェントにとっての重要性:

• sudo 不要 — flox install は完全にユーザースペースで動作するため、エージェントは昇格された権限なしでパッケージを追加できます。
• プロジェクトスコープ — パッケージはプロジェクト環境のみにインストールされ、グローバルにはインストールされないため、異なるプロジェクトで異なるバージョンを競合なく使用できます。
• サンドボックスフレンドリー — サンドボックス化または制限された環境で実行されているエージェントでも、Flox を通じて必要なツールをインストールできます。
• 元に戻せる — すべての変更は manifest.toml に記録されるため、不要なパッケージをシステムに残さずにクリーンに削除できます。
• 再現可能 — エージェントが環境をセットアップすると、その正確な設定が git にコミットされ、すべてのユーザーに対して機能します。

エージェントのワークフローパターン:

# エージェントがツールを必要としていることを検出（例：JSON 処理用の jq）
flox search jq                    # パッケージが存在することを確認
flox install jq                   # プロジェクト環境にインストール

# または、より細かく制御するためにマニフェストを直接編集
 tmp_manifest="$(mktemp)"
 flox list -c > "$tmp_manifest"
# [install] セクションにパッケージを追加し、適用
 flox edit -f "$tmp_manifest"

# ツールが利用可能な状態でコマンドを実行
flox activate -- jq '.results[]' data.json

これにより、Claude Code やその他の AI エージェントがプロジェクトのツールチェーンをその場でブートストラップする必要があるワークフローに、Flox は自然に適合します。

デバッグ

flox list -c                      # 生のマニフェストを表示
flox activate -- which python     # どのバイナリが解決されるかを確認
flox activate -- env | grep FLOX  # Flox 環境変数を表示
flox search <package> --all       # より広範なパッケージ検索（大文字小文字を区別）

よくある問題:

• パッケージが見つからない: 検索は大文字小文字を区別します — flox search --all を試してください。
• パッケージ間のファイル競合: 優先させたいパッケージに priority を追加します。
• フックの失敗: exit ではなく return を使用します。${FLOX_ENV_CACHE:-} でガードします。
• 古い依存関係: $FLOX_ENV_CACHE/.deps_installed フラグファイルを削除します。

関連スキル

以下のスキルは、より深い統合のために Flox Claude Code プラグイン の一部として利用できます:

• flox-services — サービス管理、データベースセットアップ、バックグラウンドプロセス
• flox-builds — Flox を使用した再現可能なビルドとパッケージ化
• flox-containers — Flox 環境から Docker/OCI コンテナを作成
• flox-sharing — 環境の構成、リモート環境、チームパターン
• flox-cuda — CUDA および GPU 開発環境

詳細とインストールについては、flox.dev/docs を参照してください。