flox-environments

# .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"]

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

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Semver range: latest 20.x
 
postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # Exact version

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

[install]
gcc.pkg-path = "gcc12"
gcc.priority = 3
 
clang.pkg-path = "clang_18"
clang.priority = 5               # gcc wins file conflicts

[install]
python.pkg-path = "python311"
python.pkg-group = "python-stack"
 
pip.pkg-path = "python311Packages.pip"
pip.pkg-group = "python-stack"    # Resolves together with python

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

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"
 
[hook]
on-activate = """
  if [ -f package.json ] && [ ! -d node_modules ]; then
    npm install --silent
  fi
"""

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

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

[install]
gcc.pkg-path = "gcc13"
gcc.pkg-group = "compilers"
 
# IMPORTANT: gcc alone doesn't expose libstdc++ headers — you need 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]
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 -- "$@"; }
"""

# BAD — breaks on other machines
[vars]
PROJECT_DIR = "/home/alice/projects/myapp"
 
# GOOD — use Flox environment variables
[vars]
PROJECT_DIR = "$FLOX_ENV_PROJECT"

# BAD — kills the shell
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Missing config"
    exit 1
  fi
"""
 
# GOOD — return from hook, don't exit
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Missing config — run setup first"
    return 1
  fi
"""

# BAD — manifest is committed to git
[vars]
API_KEY = "<set-at-runtime>"
 
# GOOD — reference external config or pass at runtime
# Use: API_KEY="<your-api-key>" flox activate
[vars]
API_KEY = "${API_KEY:-}"

# BAD — reinstalls every activation
[hook]
on-activate = """
  pip install -r requirements.txt
"""
 
# GOOD — skip if already installed
[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
"""

# BAD — hook functions aren't available in the interactive shell
[hook]
on-activate = """
  deploy() { kubectl apply -f k8s/; }
"""
 
# GOOD — use [profile] for user-invokable functions
[profile]
common = """
  deploy() { kubectl apply -f k8s/; }
"""

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

git add .flox/
git commit -m "Add Flox environment"
# Teammates just run:
git clone <repo> && cd <repo> && flox activate

flox push                         # Push environment to FloxHub
flox activate -r owner/env-name   # Activate remote environment anywhere

[include]
base.floxhub = "myorg/python-base"
 
[install]
# Project-specific additions on top of base
fastapi.pkg-path = "python311Packages.fastapi"

# Agent discovers it needs a tool (e.g., jq for JSON processing)
flox search jq                    # Verify the package exists
flox install jq                   # Install into project environment
 
# Or for more control, edit the manifest directly
tmp_manifest="$(mktemp)"
flox list -c > "$tmp_manifest"
# Add the package to [install] section, then apply
flox edit -f "$tmp_manifest"
 
# Run a command with the tool available
flox activate -- jq '.results[]' data.json

flox list -c                      # Show raw manifest
flox activate -- which python     # Check which binary resolves
flox activate -- env | grep FLOX  # See Flox environment variables
flox search <package> --all       # Broader package search (case-sensitive)