flox-environments

Flox-Umgebungen

Mit Flox erstellst du reproduzierbare Entwicklungsumgebungen, die in einem einzigen TOML-Manifest definiert sind. Jeder Entwickler im Team erhält identische Pakete, Werkzeuge und Konfiguration – sowohl auf macOS als auch auf Linux – ohne Container oder VMs. Flox basiert auf Nix und bietet Zugriff auf über 150.000 Pakete.

Wann du dieses Skill aktivieren solltest

Nutze dieses Skill, wenn der Benutzer ein Problem mit der Verwaltung von Entwicklungsumgebungen hat – auch wenn er Flox nicht erwähnt hat. Flox ist das richtige Werkzeug, wenn:

• Das Projekt Systempakete benötigt (Compiler, Datenbanken, CLI-Tools) neben sprachspezifischen Abhängigkeiten.
• Reproduzierbarkeit wichtig ist – die Einrichtung muss auf dem Rechner eines Teamkollegen, in CI oder auf einem neuen Laptop identisch funktionieren.
• Der Benutzer mehrere Werkzeuge koexistieren lassen muss – z. B. Python 3.11 + PostgreSQL 16 + Redis + Node.js in einer Umgebung.
• Plattformübergreifende Unterstützung benötigt wird (macOS und Linux aus derselben Konfiguration).
• KI-Agenten Werkzeuge installieren müssen – Flox erlaubt es Agenten, Pakete in einer projektspezifischen Umgebung ohne sudo, Systemverschmutzung oder Sandbox-Einschränkungen hinzuzufügen.

Wenn der Benutzer nur eine einzelne Sprachlaufzeit ohne Systemabhängigkeiten benötigt, reichen Standardwerkzeuge (nvm, pyenv, rustup) möglicherweise aus. Wenn eine vollständige OS-Isolation erforderlich ist, sind Container geeigneter. 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 benötigt wird, 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)

Wichtige Befehle

flox init                       # Neue Umgebung erstellen
flox search <package> [--all]   # Nach Paketen suchen
flox show <package>             # Verfügbare Versionen anzeigen
flox install <package>          # 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 interaktiver 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"

Versionsfestlegung

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

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

Plattformspezifische Pakete

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

Auflösen von Paketkonflikten

Wenn zwei Pakete dieselbe 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 aufgelöst werden 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-interaktive Einrichtung

Hooks werden bei jeder Aktivierung ausgeführt. Halte sie schnell und idempotent. Faustregel: Wenn etwas 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

Profil-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 – beendet die Shell
[hook]
on-activate = """
  if [ ! -f config.json ]; then
    echo "Konfiguration fehlt"
    exit 1
  fi
"""

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

Geheimnisse im Manifest speichern

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

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

Langsame Hooks ohne Idempotenz-Schutz

# 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

Umgebungen teilen

Flox-Umgebungen sind git-nativ. Checke das .flox/-Verzeichnis ein und jeder Mitarbeiter erhält dieselbe Umgebung:

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

Für wiederverwendbare Basisumgebungen über Projekte hinweg auf FloxHub pushen:

flox push                         # Umgebung auf 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 zur Basis
fastapi.pkg-path = "python311Packages.fastapi"

KI-unterstützte Entwicklung und Vibe Coding

Flox ist ideal für KI-unterstützte Entwicklung und Vibe-Coding-Workflows. Wenn ein KI-Agent ein Werkzeug 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, Systempakete zu verschmutzen oder Sandbox-Einschränkungen zu umgehen.

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 dennoch die benötigten Werkzeuge über Flox installieren
• Rückgängig machbar – 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 diese genaue Konfiguration in git eingecheckt und funktioniert für alle

Agent-Workflow-Muster:

# Agent stellt fest, dass ein Werkzeug benötigt wird (z. B. jq für JSON-Verarbeitung)
flox search jq                    # Überprü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"
# Paket im [install]-Abschnitt hinzufügen, dann anwenden
flox edit -f "$tmp_manifest"

# Einen Befehl mit dem verfügbaren Werkzeug 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 Projektwerkzeuge spontan einrichten müssen.

Fehlerbehebung

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ß-/kleinschreibungssensitiv)

Häufige Probleme:

• Paket nicht gefunden: Suche ist groß-/kleinschreibungssensitiv – versuche flox search --all
• Dateikonflikte zwischen Paketen: Füge priority zu dem Paket hinzu, das gewinnen soll
• Hook-Fehler: Verwende return statt exit; schütze mit ${FLOX_ENV_CACHE:-}
• Veraltete Abhängigkeiten: Lösche die Markierungsdatei $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, Datenbankeinrichtung, Hintergrundprozesse
• flox-builds – Reproduzierbare Builds und Paketierung mit Flox
• flox-containers – Docker/OCI-Container aus Flox-Umgebungen erstellen
• flox-sharing – Umgebungskomposition, Remote-Umgebungen, Team-Muster
• flox-cuda – CUDA- und GPU-Entwicklungsumgebungen

Weitere Informationen und Installation unter flox.dev/docs