flox

Reproducible development environments powered by Nix.

Repository: https://github.com/flox/flox Documentation: https://flox.dev/docs FloxHub: https://hub.flox.dev

---

Overview

Flox provides declarative, reproducible development environments using Nix as the package backend. Environments are defined in manifest.toml and can be shared via FloxHub.

.flox/
├── env/
│   └── manifest.toml    # Environment definition
├── env.json             # Environment metadata
└── env.lock             # Lockfile

---

Installation

# macOS
brew install flox/flox/flox

# Linux
curl -fsSL https://downloads.flox.dev/by-env/stable/install | bash

---

CLI Commands

Environment Management

flox init                    # Create new environment
flox init -n myenv           # Named environment
flox init --auto-setup       # Auto-detect languages

flox activate                # Enter environment
flox activate -d ./path      # Activate in directory
flox activate -r user/env    # Activate remote environment

flox edit                    # Edit manifest.toml
flox edit -n newname         # Rename environment

flox delete                  # Delete environment

Package Management

flox search ripgrep          # Search packages
flox show ripgrep            # Package details
flox install ripgrep         # Install package
flox uninstall ripgrep       # Remove package
flox list                    # List installed packages
flox upgrade                 # Upgrade packages
flox update                  # Update catalog

Sharing (FloxHub)

flox auth login              # OAuth2 login
flox auth logout             # Remove token
flox auth status             # Check login status

flox push                    # Push to FloxHub
flox push --force            # Overwrite remote
flox pull user/env           # Pull from FloxHub
flox pull --force            # Overwrite local

flox envs                    # List environments

Services

flox services start          # Start all services
flox services start db       # Start specific service
flox services stop           # Stop all services
flox services restart        # Restart services
flox services status         # Check service status
flox services logs db        # View logs

Containerization

flox containerize            # Create container image
flox containerize -f out.tar # Output to file
flox containerize | docker load  # Pipe to Docker

---

manifest.toml

Complete manifest reference:

# ═══════════════════════════════════════════════════════════════════
# VERSION
# ═══════════════════════════════════════════════════════════════════

version = 1

# ═══════════════════════════════════════════════════════════════════
# INSTALL - Packages to install
# ═══════════════════════════════════════════════════════════════════

[install]
ripgrep.pkg-path = "ripgrep"
nodejs.pkg-path = "nodejs"
python.pkg-path = "python312"
pip.pkg-path = "python312Packages.pip"

# With version constraints
jq.pkg-path = "jq"
jq.version = "^1.7"

# ═══════════════════════════════════════════════════════════════════
# VARS - Environment variables
# ═══════════════════════════════════════════════════════════════════

[vars]
DATABASE_URL = "postgres://localhost:5432/mydb"
NODE_ENV = "development"
GAY_SEED = "1069"

# ═══════════════════════════════════════════════════════════════════
# HOOK - Scripts run on activation
# ═══════════════════════════════════════════════════════════════════

[hook]
on-activate = """
    echo "Activating $FLOX_ENV_DESCRIPTION..."
    
    # Create Python venv
    if [ ! -d .venv ]; then
        python -m venv .venv
    fi
    
    # Export dynamic variables
    export VENV_DIR="$PWD/.venv"
    
    # Start background processes
    eval "$(ssh-agent)"
"""

# ═══════════════════════════════════════════════════════════════════
# PROFILE - Shell-specific scripts
# ═══════════════════════════════════════════════════════════════════

[profile]
common = """
    echo "Welcome to the environment"
"""

bash = """
    source .venv/bin/activate
    alias ll="ls -la"
    set -o vi
"""

zsh = """
    source .venv/bin/activate
    alias ll="ls -la"
    bindkey -v
"""

fish = """
    source .venv/bin/activate.fish
    alias ll="ls -la"
"""

# ═══════════════════════════════════════════════════════════════════
# SERVICES - Background services
# ═══════════════════════════════════════════════════════════════════

[services.postgres]
command = "postgres -D $PGDATA"
vars.PGDATA = "$FLOX_ENV_CACHE/pgdata"
vars.PGPORT = "5432"

[services.redis]
command = "redis-server"
vars.REDIS_PORT = "6379"

[services.api]
command = "npm run dev"
is-daemon = false

[services.worker]
command = "./worker.sh"
is-daemon = true
shutdown.command = "pkill -f worker.sh"

# ═══════════════════════════════════════════════════════════════════
# OPTIONS - Environment behavior
# ═══════════════════════════════════════════════════════════════════

[options]
systems = ["aarch64-darwin", "x86_64-linux"]
cuda-detection = false

[options.allow]
broken = false
unfree = true
licenses = ["MIT", "Apache-2.0"]

# ═══════════════════════════════════════════════════════════════════
# INCLUDE - Compose with other environments
# ═══════════════════════════════════════════════════════════════════

[[include.environments]]
# Remote environment from FloxHub
name = "bmorphism/effective-topos"

[[include.environments]]
# Local environment
dir = "../shared-tools"

# ═══════════════════════════════════════════════════════════════════
# CONTAINERIZE - Container image config
# ═══════════════════════════════════════════════════════════════════

[containerize.config]
cmd = ["/bin/bash", "-c", "flox activate -- npm start"]
exposed-ports = ["3000/tcp", "5432/tcp"]

---

Environment Types

Type	Location	Remote Sync	Use Case
PathEnvironment	Local .flox/	No	Personal development
ManagedEnvironment	Local + FloxHub	Yes	Team collaboration
RemoteEnvironment	FloxHub only	Read-only	Quick access

---

FloxHub Workflow

Push to FloxHub

# First time - creates managed environment
flox push

# Subsequent pushes sync changes
flox edit
flox push

# Force overwrite remote
flox push --force

Pull from FloxHub

# Clone remote environment
flox pull bmorphism/effective-topos

# Update existing managed environment
flox pull

# Force overwrite local
flox pull --force

# Copy without remote link
flox pull bmorphism/effective-topos --copy

Activate Remote

# Temporary activation (no local clone)
flox activate -r bmorphism/effective-topos

---

Services

Services use process-compose as the backend orchestrator.

Service Descriptor Options

Option	Type	Description
command	String	Bash command to start service
vars	Map	Service-specific environment variables
is-daemon	Bool	Service spawns background process
shutdown.command	String	Command to stop service (required if is-daemon)
systems	List	Compatible systems

Service Lifecycle

# Start all services
flox services start

# Check status
flox services status
# NAME      STATUS    PID
# postgres  Running   12345
# redis     Running   12346
# api       Stopped   -

# Stop specific service
flox services stop postgres

# Restart with new config
flox edit  # modify manifest
flox services restart

---

Environment Composition

Include other environments for modularity:

[[include.environments]]
name = "bmorphism/effective-topos"  # Remote

[[include.environments]]
dir = "../base-tools"               # Local

[[include.environments]]
name = "company/shared-config"

Merge Priority (lowest to highest)

1. First included environment
2. Subsequent included environments
3. Current manifest (highest priority)

Merge Behavior

Section	Behavior
[install]	Overwrite by ID
[vars]	Overwrite by key
[hook]	Append (lower → higher)
[profile]	Append (lower → higher)
[services]	Overwrite by name
[options]	Deep merge

---

Integration with Music-Topos

FloxHub Publications

Environment	Contents
bmorphism/effective-topos	606 man pages, 97 info manuals, guile, ghc, cargo
bmorphism/ies	Babashka, Julia, ffmpeg, tailscale

Activation

# Pull and activate
flox pull bmorphism/effective-topos -d ~/.topos
flox activate -d ~/.topos

# Or remote activation
flox activate -r bmorphism/effective-topos

Gay.jl Integration

[vars]
GAY_SEED = "1069"
GAY_PORT = "42069"

[services.gay-mcp]
command = "julia --project=@gay -e 'using Gay; Gay.serve_mcp()'"
vars.GAY_INTERVAL = "30"

---

Key Directories

$FLOX_ENV              # Current environment path
$FLOX_ENV_CACHE        # Persistent cache (~/.cache/flox/...)
$FLOX_ENV_PROJECT      # Project root
$FLOX_ENV_DESCRIPTION  # Human-readable name

---

Examples

Python Development

[install]
python.pkg-path = "python312"
pip.pkg-path = "python312Packages.pip"
uv.pkg-path = "uv"

[hook]
on-activate = """
    if [ ! -d .venv ]; then
        uv venv .venv
    fi
    source .venv/bin/activate
    uv pip install -r requirements.txt
"""

Node.js + PostgreSQL

[install]
nodejs.pkg-path = "nodejs_20"
postgresql.pkg-path = "postgresql_15"

[vars]
DATABASE_URL = "postgres://localhost:5432/dev"

[services.db]
command = "postgres -D $PGDATA -k $FLOX_ENV_CACHE"
vars.PGDATA = "$FLOX_ENV_CACHE/pgdata"

[hook]
on-activate = """
    if [ ! -d "$PGDATA" ]; then
        initdb -D "$PGDATA"
    fi
"""

Rust + Cargo

[install]
rustc.pkg-path = "rustc"
cargo.pkg-path = "cargo"
rust-analyzer.pkg-path = "rust-analyzer"

[vars]
CARGO_HOME = "$FLOX_ENV_CACHE/cargo"
RUSTUP_HOME = "$FLOX_ENV_CACHE/rustup"

---

References

• GitHub: https://github.com/flox/flox
• Documentation: https://flox.dev/docs
• FloxHub: https://hub.flox.dev
• DeepWiki: https://deepwiki.com/flox/flox