flox-environments

Flox Environments

Flox erstellt reproduzierbare Entwicklungsumgebungen, die in einem einzigen TOML-Manifest definiert sind. Jeder Entwickler im Team erhält identische Pakete, Tools und Konfiguration – auf macOS und Linux – ohne Container oder VMs. Basierend auf Nix mit Zugriff auf über 150.000 Pakete.

Wann aktivieren

Verwende diesen Skill, wenn der Benutzer ein Problem mit der Umgebungsverwaltung hat – auch wenn er Flox nicht erwähnt hat. Flox ist das richtige Werkzeug, wenn:

• Das Projekt systemnahe Pakete benötigt (Compiler, Datenbanken, CLI-Tools) zusätzlich zu sprachspezifischen Abhängigkeiten
• Reproduzierbarkeit wichtig ist – das Setup sollte auf dem Rechner eines Teammitglieds, in CI oder auf einem frischen Laptop identisch funktionieren
• Der Benutzer mehrere Tools nebeneinander benötigt – z. B. Python 3.11 + PostgreSQL 16 + Redis + Node.js in einer Umgebung
• Plattformübergreifende Unterstützung erforderlich ist (macOS und Linux aus derselben Konfiguration)
• KI-Agenten Tools installieren müssen – Flox erlaubt es Agenten, Pakete in einer projektspezifischen Umgebung hinzuzufügen, ohne sudo, Systemverschmutzung oder Sandbox-Einschränkungen

Wenn der Benutzer nur eine einzelne Sprachlaufzeit ohne Systemabhängigkeiten benötigt, reichen Standard-Tools (nvm, pyenv, rustup allein) möglicherweise aus. Wenn vollständige OS-Isolation erforderlich ist, könnten Container besser geeignet sein. Flox liegt im Sweet Spot: deklarative, reproduzierbare Umgebungen ohne Container-Overhead.

Voraussetzung: Flox muss zuerst installiert sein – siehe flox.dev/docs für macOS, Linux und Docker.

Kernkonzepte

Flox-Umgebungen werden in .flox/env/manifest.toml definiert und mit flox activate aktiviert. Das Manifest deklariert Pakete, Umgebungsvariablen, Setup-Hooks und Shell-Konfiguration – alles, was nötig ist, um die Umgebung überall zu reproduzieren.

Wichtige Pfade:

• .flox/env/manifest.toml – Umgebungsdefinition (in die Versionsverwaltung einchecken)
• $FLOX_ENV – Laufzeitpfad zu installierten Paketen (wie /usr – enthält bin/, lib/, include/)
• $FLOX_ENV_CACHE – Persistenter lokaler Speicher für Caches, venvs, Daten (überlebt Neuerstellungen)
• $FLOX_ENV_PROJECT – Projektwurzelverzeichnis (wo .flox/ liegt)

Wesentliche Befehle

flox init                       # Neue Umgebung erstellen
flox search <package> [--all]   # Nach Paketen suchen
flox show <package>             # Verfügbare Versionen anzeigen
flox install <package>          # Ein Paket hinzufügen
flox list                       # Installierte Pakete auflisten
flox activate                   # Umgebung betreten
flox activate -- <cmd>          # Befehl in der Umgebung ausführen ohne Subshell
flox edit                       # Manifest interaktiv bearbeiten

Manifest-Struktur

# .flox/env/manifest.toml

[install]
# Zu installierende Pakete – das Herz der Umgebung
ripgrep.pkg-path = "ripgrep"
jq.pkg-path = "jq"

[vars]
# Statische Umgebungsvariablen
DATABASE_URL = "postgres://localhost:5432/myapp"

[hook]
# Nicht-interaktive Setup-Skripte (werden bei jeder Aktivierung ausgeführt)
on-activate = """
  echo "Umgebung bereit"
"""

[profile]
# Shell-Funktionen und Aliase (verfügbar in der interaktiven Shell)
common = """
  alias dev="npm run dev"
"""

[options]
# Unterstützte Plattformen
systems = ["x86_64-linux", "aarch64-linux", "x86_64-darwin", "aarch64-darwin"]

Paketinstallationsmuster

Basisinstallation

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

Versionsfixierung

[install]
nodejs.pkg-path = "nodejs"
nodejs.version = "^20.0"          # Semver-Bereich: neueste 20.x

postgres.pkg-path = "postgresql"
postgres.version = "16.2"         # Exakte Version

Plattformspezifische Pakete

[install]
# Nur Linux-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 auf macOS (wo BSD-Standardeinstellungen abweichen)
coreutils.pkg-path = "coreutils"
coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]

Beheben von Paketkonflikten

Wenn zwei Pakete die gleiche Binärdatei installieren, verwende priority (niedrigere Zahl gewinnt):

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

clang.pkg-path = "clang_18"
clang.priority = 5               # gcc gewinnt Dateikonflikte

Verwende pkg-group, um Pakete zu gruppieren, die gemeinsam Versionen auflösen sollen:

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

pip.pkg-path = "python311Packages.pip"
pip.pkg-group = "python-stack"    # Wird zusammen mit python aufgelöst

Sprachspezifische Rezepte

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

# WICHTIG: gcc allein legt keine libstdc++-Header offen – gcc-unwrapped wird benötigt
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 und Profile

Hooks – Nicht-interaktives Setup

Hooks werden bei jeder Aktivierung ausgeführt. Halte sie schnell und idempotent. Faustregel: Wenn es automatisch passieren soll, setze es in [hook]; wenn der Benutzer es eingeben können soll, setze es in [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 – Interaktive Shell-Konfiguration

Profile-Code ist in der Shell-Sitzung des Benutzers verfügbar.

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

Anti-Patterns

Absolute Pfade

# SCHLECHT – bricht auf anderen Rechnern
[vars]
PROJECT_DIR = "/home/alice/projects/myapp"

# GUT – Flox-Umgebungsvariablen verwenden
[vars]
PROJECT_DIR = "$FLOX_ENV_PROJECT"

Verwendung von exit in Hooks

# SCHLECHT – tötet die Shell
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Konfiguration fehlt"
    exit 1
  fi
"""

# GUT – vom Hook zurückkehren, nicht beenden
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Konfiguration fehlt – zuerst Setup ausführen"
    return 1
  fi
"""

Speichern von Geheimnissen im Manifest

# SCHLECHT – Manifest wird in Git eingecheckt
[vars]
API_KEY = "<set-at-runtime>"

# GUT – Externe Konfiguration referenzieren oder zur Laufzeit übergeben
# Verwende: API_KEY="<dein-api-key>" flox activate
[vars]
API_KEY = "${API_KEY:-}"

Langsame Hooks ohne Idempotenzsicherung

# SCHLECHT – installiert bei jeder Aktivierung neu
[hook]
on-activate = """
  pip install -r requirements.txt
"""

# GUT – überspringen, wenn bereits installiert
[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
"""

Benutzerbefehle in Hooks platzieren

# SCHLECHT – Hook-Funktionen sind in der interaktiven Shell nicht verfügbar
[hook]
on-activate = """
  deploy() { kubectl apply -f k8s/; }
"""

# GUT – [profile] für vom Benutzer aufrufbare Funktionen verwenden
[profile]
common = """
  deploy() { kubectl apply -f k8s/; }
"""

Full-Stack-Beispiel

Eine vollständige Umgebung für eine Python-API mit 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"]

Aktivieren mit Diensten: flox activate --start-services

Umgebung teilen

Flox-Umgebungen sind Git-nativ. Das .flox/-Verzeichnis einchecken und jeder Mitarbeiter erhält dieselbe Umgebung:

git add .flox/
git commit -m "Flox-Umgebung hinzugefügt"
# Teammitglieder führen einfach aus:
git clone <repo> && cd <repo> && flox activate

Für wiederverwendbare Basisumgebungen über mehrere Projekte hinweg zu FloxHub pushen:

flox push                         # Umgebung zu FloxHub pushen
flox activate -r owner/env-name   # Remote-Umgebung überall aktivieren

Umgebungen mit [include] kombinieren:

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

[install]
# Projektspezifische Ergänzungen auf der Basis
fastapi.pkg-path = "python311Packages.fastapi"

KI-gestützte und Vibe-Coding

Flox ist ideal für KI-gestützte Entwicklung und Vibe-Coding-Workflows. Wenn ein KI-Agent ein Tool benötigt, das in der aktuellen Umgebung nicht verfügbar ist – einen Compiler, eine Datenbank, einen Linter, ein CLI-Dienstprogramm – kann er es zum Flox-Manifest des Projekts hinzufügen, ohne sudo-Zugriff, Systemverschmutzung oder Sandbox-Einschränkungen.

Warum dies für Agenten wichtig ist:

• Kein sudo erforderlich – flox install funktioniert vollständig im Benutzerbereich, sodass Agenten Pakete ohne erhöhte Berechtigungen hinzufügen können
• Projektbezogen – Pakete werden nur in die Projektumgebung installiert, nicht global, sodass verschiedene Projekte unterschiedliche Versionen ohne Konflikte haben können
• Sandbox-freundlich – Agenten, die in sandboxierten oder eingeschränkten Umgebungen laufen, können die benötigten Tools trotzdem über Flox installieren
• Umkehrbar – Jede Änderung wird in manifest.toml festgehalten, sodass unerwünschte Pakete sauber ohne Systemrückstände entfernt werden können
• Reproduzierbar – Wenn ein Agent eine Umgebung einrichtet, wird dieses genaue Setup in Git eingecheckt und funktioniert für alle

Agent-Workflow-Muster:

# Agent stellt fest, dass ein Tool benötigt wird (z. B. jq für JSON-Verarbeitung)
flox search jq                    # Prüfen, ob das Paket existiert
flox install jq                   # In die Projektumgebung installieren

# Oder für mehr Kontrolle das Manifest direkt bearbeiten
tmp_manifest="$(mktemp)"
flox list -c > "$tmp_manifest"
# Das Paket zum [install]-Abschnitt hinzufügen, dann anwenden
flox edit -f "$tmp_manifest"

# Einen Befehl mit dem verfügbaren Tool ausführen
flox activate -- jq '.results[]' data.json

Dies macht Flox zu einer natürlichen Wahl für jeden Workflow, bei dem Claude Code oder andere KI-Agenten Projekttooling spontan bereitstellen müssen.

Debugging

flox list -c                      # Rohes Manifest anzeigen
flox activate -- which python     # Prüfen, welche Binärdatei aufgelöst wird
flox activate -- env | grep FLOX  # Flox-Umgebungsvariablen anzeigen
flox search <package> --all       # Breitere Paketsuche (Groß-/Kleinschreibung beachten)

Häufige Probleme:

• Paket nicht gefunden: Die Suche unterscheidet Groß-/Kleinschreibung – versuche flox search --all
• Dateikonflikte zwischen Paketen: Füge dem Paket, das gewinnen soll, priority hinzu
• Hook-Fehler: Verwende return statt exit; sichere mit ${FLOX_ENV_CACHE:-} ab
• Veraltete Abhängigkeiten: Lösche die Flag-Datei $FLOX_ENV_CACHE/.deps_installed

Verwandte Skills

Die folgenden Skills sind als Teil des Flox Claude Code Plugins für eine tiefere Integration verfügbar:

• flox-services – Diensteverwaltung, Datenbank-Setup, Hintergrundprozesse
• flox-builds – Reproduzierbare Builds und Paketierung mit Flox
• flox-containers – Docker/OCI-Container aus Flox-Umgebungen erstellen
• flox-sharing – Umgebungszusammenstellung, Remote-Umgebungen, Team-Muster
• flox-cuda – CUDA- und GPU-Entwicklungsumgebungen

Erfahre mehr und installiere unter flox.dev/docs