name	flox
description	Reproducible development environments powered by Nix.
version	1.0.0

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)

First included environment
Subsequent included environments
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

Scientific Skill Interleaving

This skill connects to the K-Dense-AI/claude-scientific-skills ecosystem:

Graph Theory

networkx [○] via bicomodule
- Universal graph hub

Bibliography References

general: 734 citations in bib.duckdb

Cat# Integration

This skill maps to Cat# = Comod(P) as a bicomodule in the equipment structure:

Trit: 0 (ERGODIC)
Home: Prof
Poly Op: ⊗
Kan Role: Adj
Color: #26D826

GF(3) Naturality

The skill participates in triads satisfying:

(-1) + (0) + (+1) ≡ 0 (mod 3)

This ensures compositional coherence in the Cat# equipment structure.

flox

Install Skill

SKILL.md

flox

Overview

Installation

CLI Commands

Environment Management

Package Management

Sharing (FloxHub)

Services

Containerization

manifest.toml

Environment Types

FloxHub Workflow

Push to FloxHub

Pull from FloxHub

Activate Remote

Services

Service Descriptor Options

Service Lifecycle

Environment Composition

Merge Priority (lowest to highest)

Merge Behavior

Integration with Music-Topos

FloxHub Publications

Activation

Gay.jl Integration

Key Directories

Examples

Python Development

Node.js + PostgreSQL

Rust + Cargo

References

Scientific Skill Interleaving

Graph Theory

Bibliography References

Cat# Integration

GF(3) Naturality