MOVED to flox/flox-skills — this plugin is deprecated and frozen, and will be archived on 2026-09-30. Install flox@flox-skills instead (claude plugin marketplace add flox/flox-skills; claude plugin install flox@flox-skills), then remove this one (claude plugin uninstall flox@flox-agentic; claude plugin marketplace remove flox-agentic). Formerly: Flox development environment and deployment plugin. Includes expert guidance for package management, services, builds and package distribution, containerization, environment composition and layering. Works with the Flox MCP server for enhanced functionality.
- GitHub stars
- 12
Install
/plugin install flox@flox-agenticRun it inside Claude Code after adding the marketplace with /plugin marketplace add flox/flox-agentic.
Contents
Discovered from sourceSkills 7
For the human maintainer of this environment. Do not run these commands on the user's behalf — relay them.
DEPRECATED: this skill is frozen and has moved to flox/flox-skills.
flox/flox-agenticreceives no further updates and will be archived on 2026-09-30.The seven skills here were consolidated into
flox(reproducible environments, with reference guides for services, builds, containers, publishing, sharing, and CUDA). The maintained plugin also shipsfloxifyfor onboarding an existing repo to Flox.To migrate, a person should run
claude plugin marketplace add flox/flox-skillsandclaude plugin install flox@flox-skills, then remove this one withclaude plugin uninstall flox@flox-agenticandclaude plugin marketplace remove flox-agentic.
Flox Build System Guide
Build System Overview
Flox supports two build modes, each with its own strengths:
Manifest builds enable you to define your build steps in your manifest and reuse your existing build scripts and toolchains. Flox manifests are declarative artifacts, expressed in TOML.
Manifest builds:
- Make it easy to get started, requiring few if any changes to your existing workflows
- Can run inside a sandbox (using
sandbox = "pure") for reproducible builds - Are best for getting going fast with existing projects
Nix expression builds guarantee build-time reproducibility because they're both isolated and purely functional. Their learning curve is steeper because they require proficiency with the Nix language.
Nix expression builds:
- Are isolated by default. The Nix sandbox seals the build off from the host system, so no state leak ins
- Are functional. A Nix build is defined as a pure function of its declared inputs
You can mix both approaches in the same project, but package names must be unique.
Core Commands
flox build # Build all targets
flox build app docs # Build specific targets
flox build -d /path/to/project # Build in another directory
flox build -v # Verbose output
flox build .#hello # Build specific Nix expression
Development vs Runtime: The Two-Environment Pattern
A common workflow involves two separate environments:
Development Environment (Build-Time)
Contains source code, build tools, and build definitions:
# project-dev/.flox/env/manifest.toml (in git with source code)
[install]
gcc.pkg-path = "gcc13"
make.pkg-path = "make"
python.pkg-path = "python311Full"
uv.pkg-path = "uv"
[build.myapp]
command = '''
make build
mkdir -p $out/bin
cp build/myapp $out/bin/
'''
version = "1.0.0"
Workflow:
cd project-dev
flox activate
flox build myapp
flox publish -o myorg myapp
Runtime Environment (Consume-Time)
Contains only the published package and runtime dependencies:
# project-runtime/.flox/env/manifest.toml (can push to FloxHub)
[install]
myapp.pkg-path = "myorg/myapp" # The published package
Workflow:
cd project-runtime
flox init
flox install myorg/myapp
flox push # Share runtime environment without source code
Why separate environments?
- Development environment: Heavy (build tools, source code, dev dependencies)
- Runtime environment: Lightweight (only published package and runtime needs)
- Security: Runtime environments don't expose source code
- Clarity: Clear separation between building and consuming
- Rollback: Can rollback the live generation of a runtime environment without affecting the development environment
Note: You can also install published packages into existing environments (other projects, production environments, etc.), not just dedicated runtime environments.
Manifest Builds
Flox treats a manifest build as a short, deterministic Bash script that runs inside an activated environment and copies its deliverables into $out. Anything copied there becomes a first-class, versioned package that can later be published and installed like any other catalog artifact.
Critical insights from real-world packaging:
- Build hooks don't run:
[hook]scripts DO NOT execute duringflox build- only during interactiveflox activate - Guard env vars: Always use
${FLOX_ENV_CACHE:-}with default fallback in hooks to avoid build failures - Wrapper scripts pattern: Create launcher scripts in
$out/bin/that set up runtime environment:cat > "$out/bin/myapp" << 'EOF' #!/usr/bin/env bash APP_ROOT="$(dirname "$(dirname "$(readlink -f "$0")")")" export PYTHONPATH="$APP_ROOT/share/myapp:$PYTHONPATH" exec python3 "$APP_ROOT/share/myapp/main.py" "$@" EOF chmod +x "$out/bin/myapp" - User config pattern: Default to
~/.myapp/for user configs, not$FLOX_ENV_CACHE(packages are immutable) - Model/data directories: Create user directories at runtime, not build time:
mkdir -p "${MYAPP_DIR:-$HOME/.myapp}/models" - Python package strategy: Don't bundle Python deps - include
requirements.txtand setup script:# In build, create setup script: cat > "$out/bin/myapp-setup" << 'EOF' venv="${VENV:-$HOME/.myapp/venv}" uv venv "$venv" --python python3 uv pip install --python "$venv/bin/python" -r "$APP_ROOT/share/myapp/requirements.txt" EOF - Dual-environment workflow: Use one environment for building (
project-dev/), another for consuming (project-runtime/). See "Development vs Runtime: The Two-Environment Pattern" section above for details.
Build Definition Syntax
[build.<name>]
command = ''' # required – Bash, multiline string
<your build steps> # e.g. cargo build, npm run build
mkdir -p $out/bin
cp path/to/artifact $out/bin/<name>
'''
version = "1.2.3" # optional
description = "one-line summary" # optional
sandbox = "pure" | "off" # default: off
runtime-packages = [ "id1", "id2" ] # optional
One table per package. Multiple [build.*] tables let you publish, for example, a stripped release binary and a debug build from the same sources.
Bash only. The script executes under set -euo pipefail. If you need zsh or fish features, invoke them explicitly inside the script.
Environment parity. Before your script runs, Flox performs the equivalent of flox activate — so every tool listed in [install] is on PATH.
Package groups and builds. Only packages in the toplevel group (default) are available during builds. Packages with explicit pkg-group settings won't be accessible in build commands unless also installed to toplevel.
Referencing other builds. ${other} expands to the $out of [build.other] and forces that build to run first, enabling multi-stage flows (e.g. vendoring → compilation).
Purity and Sandbox Control
| sandbox value | Filesystem scope | Network | Typical use-case |
|---|---|---|---|
"off" (default) | Project working tree; complete host FS | allowed | Fast, iterative dev builds |
"pure" | Git-tracked files only, copied to tmp | Linux: blocked macOS: allowed | Reproducible, host-agnostic packages |
Pure mode highlights undeclared inputs early and is mandatory for builds intended for CI/CD publication. When a pure build needs pre-fetched artifacts (e.g. language modules) use a two-stage pattern:
[build.deps]
command = '''go mod vendor -o $out/etc/vendor'''
sandbox = "off"
[build.app]
command = '''
cp -r ${deps}/etc/vendor ./vendor
go build ./...
mkdir -p $out/bin
cp app $out/bin/
'''
sandbox = "pure"
$out Layout and Filesystem Hierarchy
Only files placed under $out survive. Follow FHS conventions:
| Path | Purpose |
|---|---|
$out/bin / $out/sbin | CLI and daemon binaries (must be chmod +x) |
$out/lib, $out/libexec | Shared libraries, helper programs |
$out/share/man | Man pages (gzip them) |
$out/etc | Configuration shipped with the package |
Scripts or binaries stored elsewhere will not end up on callers' paths.
Running Manifest Builds
# Build every target in the manifest
flox build
# Build a subset
flox build app docs
# Build a manifest in another directory
flox build -d /path/to/project
Results appear as immutable symlinks: ./result-<name> → /nix/store/...-<name>-<version>.
To execute a freshly built binary: ./result-app/bin/app.
Multi-Stage Examples
Rust release binary plus source tar
[build.bin]
command = '''
cargo build --release
mkdir -p $out/bin
cp target/release/myproject $out/bin/
'''
version = "0.9.0"
[build.src]
command = '''
git archive --format=tar HEAD | gzip > $out/myproject-${bin.version}.tar.gz
'''
sandbox = "pure"
${bin.version} resolves because both builds share the same manifest.
Go with vendored dependencies
[build.vendor]
command = '''
go mod vendor
mkdir -p $out/vendor
cp -r vendor/* $out/vendor/
'''
sandbox = "off"
[build.app]
command = '''
cp -r ${vendor}/vendor ./
go build -mod=vendor -o $out/bin/myapp
'''
sandbox = "pure"
Trimming Runtime Dependencies
By default, every package in the toplevel install-group becomes a runtime dependency of your build's closure—even if it was only needed at compile time.
Declare a minimal list instead:
[install]
clang.pkg-path = "clang"
pytest.pkg-path = "pytest"
[build.cli]
command = '''
make
mv build/cli $out/bin/
'''
runtime-packages = [ "clang" ] # exclude pytest from runtime closure
Smaller closures copy faster and occupy less disk when installed on users' systems.
Version and Description Metadata
Flox surfaces these fields in flox search, flox show, and during publication.
[build.mytool]
version.command = "git describe --tags"
description = "High-performance log shipper"
Alternative forms:
version = "1.4.2" # static string
version.file = "VERSION.txt" # read at build time
Cross-Platform Considerations for Manifest Builds
flox build targets the host's systems triple. To ship binaries for additional platforms you must trigger the build on machines (or CI runners) of those architectures:
linux-x86_64 → build → publish
darwin-aarch64 → build → publish
The manifest can remain identical across hosts.
Beyond Code — Packaging Assets
Any artifact that can be copied into $out can be versioned and installed:
Nginx baseline config
[build.nginx_cfg]
command = '''mkdir -p $out/etc && cp nginx.conf $out/etc/'''
Organization-wide .proto schema bundle
[build.proto]
command = '''
mkdir -p $out/share/proto
cp proto/**/*.proto $out/share/proto/
'''
Teams install these packages and reference them via $FLOX_ENV/etc/nginx.conf or $FLOX_ENV/share/proto.
Nix Expression Builds
You can write a Nix expression instead of (or in addition to) defining a manifest build.
Put *.nix build files in .flox/pkgs/ for Nix expression builds. Git add all files before building.
File Naming
hello.nix→ package namedhellohello/default.nix→ package namedhello
Common Patterns
Shell Script
{writeShellApplication, curl}:
writeShellApplication {
name = "my-ip";
runtimeInputs = [ curl ];
text = ''curl icanhazip.com'';
}
Your Project
{ rustPlatform, lib }:
rustPlatform.buildRustPackage {
pname = "my-app";
version = "0.1.0";
src = ../../.;
cargoLock.lockFile = "${src}/Cargo.lock";
}
Update Version
{ hello, fetchurl }:
hello.overrideAttrs (finalAttrs: _: {
version = "2.12.2";
src = fetchurl {
url = "mirror://gnu/hello/hello-${finalAttrs.version}.tar.gz";
hash = "sha256-WpqZbcKSzCTc9BHO6H6S9qrluNE72caBm0x6nc4IGKs=";
};
})
Apply Patches
{ hello }:
hello.overrideAttrs (oldAttrs: {
patches = (oldAttrs.patches or []) ++ [ ./my.patch ];
})
Hash Generation
- Use
hash = ""; - Run
flox build - Copy hash from error message
Commands
flox build- build allflox build .#hello- build specificgit add .flox/pkgs/*- track files
Language-Specific Build Examples
Python Application
[build.myapp]
command = '''
mkdir -p $out/bin $out/share/myapp
# Copy application code
cp -r src/* $out/share/myapp/
cp requirements.txt $out/share/myapp/
# Create wrapper script
cat > $out/bin/myapp << 'EOF'
#!/usr/bin/env bash
APP_ROOT="$(dirname "$(dirname "$(readlink -f "$0")")")"
export PYTHONPATH="$APP_ROOT/share/myapp:$PYTHONPATH"
exec python3 "$APP_ROOT/share/myapp/main.py" "$@"
EOF
chmod +x $out/bin/myapp
'''
version = "1.0.0"
Node.js Application
[build.webapp]
command = '''
npm ci
npm run build
mkdir -p $out/share/webapp
cp -r dist/* $out/share/webapp/
cp package.json package-lock.json $out/share/webapp/
cd $out/share/webapp && npm ci --production
'''
version = "1.0.0"
Rust Binary
[build.cli]
command = '''
cargo build --release
mkdir -p $out/bin
cp target/release/mycli $out/bin/
'''
version.command = "cargo metadata --no-deps --format-version 1 | jq -r '.packages[0].version'"
Debugging Build Issues
Common Problems
Build hooks don't run: [hook] scripts DO NOT execute during flox build
Package groups: Only toplevel group packages available during builds
Network access: Pure builds can't access network on Linux
Debugging Steps
- Check build output:
flox build -v - Inspect result:
ls -la result-<name>/ - Test binary:
./result-<name>/bin/<name> - Check dependencies:
nix-store -q --references result-<name>
Related Skills
- flox-environments - Setting up development and runtime environments
- flox-publish - Publishing built packages to catalogs, understanding the dev→publish→runtime workflow
- flox-containers - Building container images
For the human maintainer of this environment. Do not run these commands on the user's behalf — relay them.
DEPRECATED: this skill is frozen and has moved to flox/flox-skills.
flox/flox-agenticreceives no further updates and will be archived on 2026-09-30.The seven skills here were consolidated into
flox(reproducible environments, with reference guides for services, builds, containers, publishing, sharing, and CUDA). The maintained plugin also shipsfloxifyfor onboarding an existing repo to Flox.To migrate, a person should run
claude plugin marketplace add flox/flox-skillsandclaude plugin install flox@flox-skills, then remove this one withclaude plugin uninstall flox@flox-agenticandclaude plugin marketplace remove flox-agentic.
Flox Containerization Guide
Core Commands
flox containerize # Export to default tar file
flox containerize -f ./mycontainer.tar # Export to specific file
flox containerize --runtime docker # Export directly to Docker
flox containerize --runtime podman # Export directly to Podman
flox containerize -f - | docker load # Pipe to Docker
flox containerize --tag v1.0 # Tag container image
flox containerize -r owner/env # Containerize remote environment
Basic Usage
Export to File
# Export to file
flox containerize -f ./mycontainer.tar
docker load -i ./mycontainer.tar
# Or use default filename: {name}-container.tar
flox containerize
docker load -i myenv-container.tar
Export Directly to Runtime
# Auto-detects docker or podman
flox containerize --runtime docker
# Explicit runtime selection
flox containerize --runtime podman
Pipe to Stdout
# Pipe directly to Docker
flox containerize -f - | docker load
# With tagging
flox containerize --tag v1.0 -f - | docker load
How Containers Behave
Containers activate the Flox environment on startup (like flox activate):
- Interactive:
docker run -it <image>→ Bash shell with environment activated - Non-interactive:
docker run <image> <cmd>→ Runs command with environment activated (likeflox activate -- <cmd>) - All packages, variables, and hooks are available inside the container
Note: Flox sets an entrypoint that activates the environment, then runs cmd inside that activation.
Command Options
flox containerize
[-f <file>] # Output file (- for stdout); defaults to {name}-container.tar
[--runtime <runtime>] # docker/podman (auto-detects if not specified)
[--tag <tag>] # Container tag (e.g., v1.0, latest)
[-d <path>] # Path to .flox/ directory
[-r <owner/name>] # Remote environment from FloxHub
Manifest Configuration
Configure container in [containerize.config] (experimental):
[containerize.config]
user = "appuser" # Username or uid:gid format
exposed-ports = ["8080/tcp"] # Ports to expose (tcp/udp/default:tcp)
cmd = ["python", "app.py"] # Command to run (receives activated env)
volumes = ["/data", "/config"] # Mount points for persistent data
working-dir = "/app" # Working directory
labels = { version = "1.0" } # Arbitrary metadata
stop-signal = "SIGTERM" # Signal to stop container
Configuration Options Explained
user: Run container as specific user
- Username:
user = "appuser" - UID:GID:
user = "1000:1000"
exposed-ports: Network ports to expose
- TCP:
["8080/tcp"] - UDP:
["8125/udp"] - Default protocol is tcp:
["8080"]=["8080/tcp"]
cmd: Command to run in container
- Array form:
cmd = ["python", "app.py"] - Empty for service-based:
cmd = []
volumes: Mount points for persistent data
- List paths:
volumes = ["/data", "/config", "/logs"]
working-dir: Initial working directory
- Absolute path:
working-dir = "/app"
labels: Arbitrary metadata
- Key-value pairs:
labels = { version = "1.0", env = "production" }
stop-signal: Signal to stop container
- Common:
"SIGTERM","SIGINT","SIGKILL"
Complete Workflow Examples
Flask Web Application
# Create environment
flox init
flox install python311 flask
# Configure for container
cat >> .flox/env/manifest.toml << 'EOF'
[containerize.config]
exposed-ports = ["5000/tcp"]
cmd = ["python", "-m", "flask", "run", "--host=0.0.0.0"]
working-dir = "/app"
user = "flask"
EOF
# Build and run
flox containerize -f - | docker load
docker run -p 5000:5000 -v $(pwd):/app <container-id>
Node.js Application
flox init
flox install nodejs
cat >> .flox/env/manifest.toml << 'EOF'
[containerize.config]
exposed-ports = ["3000/tcp"]
cmd = ["npm", "start"]
working-dir = "/app"
EOF
flox containerize --tag myapp:latest --runtime docker
docker run -p 3000:3000 -v $(pwd):/app myapp:latest
Database Container
flox init
flox install postgresql
# Set up service in manifest
flox edit
# Add service and container config
cat >> .flox/env/manifest.toml << 'EOF'
[services.postgres]
command = '''
mkdir -p /data/postgres
if [ ! -d "/data/postgres/pgdata" ]; then
initdb -D /data/postgres/pgdata
fi
exec postgres -D /data/postgres/pgdata -h 0.0.0.0
'''
is-daemon = true
[containerize.config]
exposed-ports = ["5432/tcp"]
volumes = ["/data"]
cmd = [] # Service starts automatically
EOF
flox containerize -f - | docker load
docker run -p 5432:5432 -v pgdata:/data <container-id>
Common Patterns
Service Containers
Services start automatically when cmd is empty:
[services.web]
command = "python -m http.server 8000"
[containerize.config]
exposed-ports = ["8000/tcp"]
cmd = [] # Service starts automatically
Multi-Stage Pattern
Build in one environment, run in another:
# Build environment with all dev tools
cd build-env
flox activate -- flox build myapp
# Runtime environment with minimal deps
cd ../runtime-env
flox install myapp
flox containerize --tag production -f - | docker load
# Run
docker run production
Remote Environment Containers
Containerize shared team environments:
# Containerize remote environment
flox containerize -r team/python-ml --tag latest --runtime docker
# Run it
docker run -it team-python-ml:latest
Multi-Service Container
[services.db]
command = '''exec postgres -D "$FLOX_ENV_CACHE/postgres"'''
is-daemon = true
[services.cache]
command = '''exec redis-server'''
is-daemon = true
[services.api]
command = '''exec python -m uvicorn main:app --host 0.0.0.0'''
[containerize.config]
exposed-ports = ["8000/tcp", "5432/tcp", "6379/tcp"]
cmd = [] # All services start automatically
Platform-Specific Notes
macOS
- Requires docker/podman runtime (uses proxy container for builds)
- May prompt for file sharing permissions
- Creates
flox-nixvolume for caching - Safe to remove when not building:
docker volume rm flox-nix
Linux
- Direct image creation without proxy
- No intermediate volumes needed
- Native container support
Advanced Use Cases
Custom Entrypoint with Wrapper Script
[build.entrypoint]
command = '''
cat > $out/bin/entrypoint.sh << 'EOF'
#!/usr/bin/env bash
set -e
# Custom initialization
echo "Initializing application..."
setup_app
# Run whatever command was passed
exec "$@"
EOF
chmod +x $out/bin/entrypoint.sh
'''
[containerize.config]
cmd = ["entrypoint.sh", "python", "app.py"]
Health Check Support
[containerize.config]
cmd = ["python", "app.py"]
labels = {
"healthcheck" = "curl -f http://localhost:8000/health || exit 1"
}
Then in Docker:
docker run --health-cmd="curl -f http://localhost:8000/health || exit 1" \
--health-interval=30s \
myimage
Multi-Architecture Builds
Build for different architectures:
# On x86_64 Linux
flox containerize --tag myapp:amd64 --runtime docker
# On ARM64 (aarch64) Linux
flox containerize --tag myapp:arm64 --runtime docker
# Create manifest
docker manifest create myapp:latest \
myapp:amd64 \
myapp:arm64
Minimal Container Size
Create minimal runtime environment:
[install]
# Only runtime dependencies
python.pkg-path = "python311"
# No dev tools, no build tools
[build.app]
command = '''
# Build in build environment
python -m pip install --target=$out/lib/python -r requirements.txt
cp -r src $out/lib/python/
'''
runtime-packages = ["python"]
[containerize.config]
cmd = ["python", "-m", "myapp"]
Container Registry Workflows
Push to Registry
# Build container
flox containerize --tag myapp:v1.0 --runtime docker
# Tag for registry
docker tag myapp:v1.0 registry.company.com/myapp:v1.0
# Push
docker push registry.company.com/myapp:v1.0
GitLab CI/CD
containerize:
stage: build
script:
- flox containerize --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG --runtime docker
- docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
GitHub Actions
- name: Build container
run: |
flox containerize --tag ghcr.io/${{ github.repository }}:${{ github.sha }} --runtime docker
- name: Push to GHCR
run: |
echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
docker push ghcr.io/${{ github.repository }}:${{ github.sha }}
Kubernetes Deployment
Basic Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
name: myapp
spec:
replicas: 3
selector:
matchLabels:
app: myapp
template:
metadata:
labels:
app: myapp
spec:
containers:
- name: myapp
image: registry.company.com/myapp:v1.0
ports:
- containerPort: 8000
volumeMounts:
- name: data
mountPath: /data
volumes:
- name: data
persistentVolumeClaim:
claimName: myapp-data
Service Definition
apiVersion: v1
kind: Service
metadata:
name: myapp
spec:
selector:
app: myapp
ports:
- port: 80
targetPort: 8000
type: LoadBalancer
Debugging Container Issues
Inspect Container
# Run interactively
docker run -it --entrypoint /bin/bash <image-id>
# Check environment
docker run <image-id> env
# Check what's in the image
docker run <image-id> ls -la /
View Container Logs
# Follow logs
docker logs -f <container-id>
# Last 100 lines
docker logs --tail 100 <container-id>
Execute Commands in Running Container
# Get a shell
docker exec -it <container-id> /bin/bash
# Run specific command
docker exec <container-id> flox list
Best Practices
- Use specific tags: Avoid
latest, use semantic versioning - Minimize layers: Combine related operations in manifests
- Use .dockerignore equivalent: Only include necessary files in build context
- Health checks: Implement health check endpoints for services
- Security: Run as non-root user when possible
- Volumes: Use volumes for persistent data, not container filesystem
- Environment variables: Make configuration overridable via env vars
- Logging: Log to stdout/stderr, not files
Related Skills
- flox-environments - Creating environments to containerize
- flox-services - Running services in containers
- flox-builds - Building artifacts before containerizing
- flox-sharing - Containerizing remote environments
For the human maintainer of this environment. Do not run these commands on the user's behalf — relay them.
DEPRECATED: this skill is frozen and has moved to flox/flox-skills.
flox/flox-agenticreceives no further updates and will be archived on 2026-09-30.The seven skills here were consolidated into
flox(reproducible environments, with reference guides for services, builds, containers, publishing, sharing, and CUDA). The maintained plugin also shipsfloxifyfor onboarding an existing repo to Flox.To migrate, a person should run
claude plugin marketplace add flox/flox-skillsandclaude plugin install flox@flox-skills, then remove this one withclaude plugin uninstall flox@flox-agenticandclaude plugin marketplace remove flox-agentic.
Flox CUDA Development Guide
Prerequisites & Authentication
- Sign up for early access at https://flox.dev
- Authenticate with
flox auth login - Linux-only: CUDA packages only work on
["aarch64-linux", "x86_64-linux"] - All CUDA packages are prefixed with
flox-cuda/in the catalog - No macOS support: Use Metal alternatives on Darwin
Core Commands
# Search for CUDA packages
flox search cudatoolkit --all | grep flox-cuda
flox search nvcc --all | grep 12_8
# Show available versions
flox show flox-cuda/cudaPackages.cudatoolkit
# Install CUDA packages
flox install flox-cuda/cudaPackages_12_8.cuda_nvcc
flox install flox-cuda/cudaPackages.cuda_cudart
# Verify installation
nvcc --version
nvidia-smi
Package Discovery
# Search for CUDA toolkit
flox search cudatoolkit --all | grep flox-cuda
# Search for specific versions
flox search nvcc --all | grep 12_8
# Show all available versions
flox show flox-cuda/cudaPackages.cudatoolkit
# Search for CUDA libraries
flox search libcublas --all | grep flox-cuda
flox search cudnn --all | grep flox-cuda
Essential CUDA Packages
| Package Pattern | Purpose | Example |
|---|---|---|
cudaPackages_X_Y.cudatoolkit | Main CUDA Toolkit | cudaPackages_12_8.cudatoolkit |
cudaPackages_X_Y.cuda_nvcc | NVIDIA C++ Compiler | cudaPackages_12_8.cuda_nvcc |
cudaPackages.cuda_cudart | CUDA Runtime API | cuda_cudart |
cudaPackages_X_Y.libcublas | Linear algebra | cudaPackages_12_8.libcublas |
cudaPackages_X_Y.libcufft | Fast Fourier Transform | cudaPackages_12_8.libcufft |
cudaPackages_X_Y.libcurand | Random number generation | cudaPackages_12_8.libcurand |
cudaPackages_X_Y.cudnn_9_11 | Deep neural networks | cudaPackages_12_8.cudnn_9_11 |
cudaPackages_X_Y.nccl | Multi-GPU communication | cudaPackages_12_8.nccl |
Critical: Conflict Resolution
CUDA packages have LICENSE file conflicts requiring explicit priorities:
[install]
cuda_nvcc.pkg-path = "flox-cuda/cudaPackages_12_8.cuda_nvcc"
cuda_nvcc.systems = ["aarch64-linux", "x86_64-linux"]
cuda_nvcc.priority = 1 # Highest priority
cuda_cudart.pkg-path = "flox-cuda/cudaPackages.cuda_cudart"
cuda_cudart.systems = ["aarch64-linux", "x86_64-linux"]
cuda_cudart.priority = 2
cudatoolkit.pkg-path = "flox-cuda/cudaPackages_12_8.cudatoolkit"
cudatoolkit.systems = ["aarch64-linux", "x86_64-linux"]
cudatoolkit.priority = 3 # Lower for LICENSE conflicts
gcc.pkg-path = "gcc"
gcc-unwrapped.pkg-path = "gcc-unwrapped" # For libstdc++
gcc-unwrapped.priority = 5
CUDA Version Selection
CUDA 12.x (Current)
[install]
cuda_nvcc.pkg-path = "flox-cuda/cudaPackages_12_8.cuda_nvcc"
cuda_nvcc.priority = 1
cuda_nvcc.systems = ["aarch64-linux", "x86_64-linux"]
cudatoolkit.pkg-path = "flox-cuda/cudaPackages_12_8.cudatoolkit"
cudatoolkit.priority = 3
cudatoolkit.systems = ["aarch64-linux", "x86_64-linux"]
CUDA 11.x (Legacy Support)
[install]
cuda_nvcc.pkg-path = "flox-cuda/cudaPackages_11_8.cuda_nvcc"
cuda_nvcc.priority = 1
cuda_nvcc.systems = ["aarch64-linux", "x86_64-linux"]
cudatoolkit.pkg-path = "flox-cuda/cudaPackages_11_8.cudatoolkit"
cudatoolkit.priority = 3
cudatoolkit.systems = ["aarch64-linux", "x86_64-linux"]
Cross-Platform GPU Development
Dual CUDA/CPU packages for portability (Linux gets CUDA, macOS gets CPU fallback):
[install]
## CUDA packages (Linux only)
cuda-pytorch.pkg-path = "flox-cuda/python3Packages.torch"
cuda-pytorch.systems = ["x86_64-linux", "aarch64-linux"]
cuda-pytorch.priority = 1
## Non-CUDA packages (macOS + Linux fallback)
pytorch.pkg-path = "python313Packages.pytorch"
pytorch.systems = ["x86_64-darwin", "aarch64-darwin"]
pytorch.priority = 6 # Lower priority
GPU Detection Pattern
Dynamic CPU/GPU package installation in hooks:
setup_gpu_packages() {
venv="$FLOX_ENV_CACHE/venv"
if [ ! -f "$FLOX_ENV_CACHE/.deps_installed" ]; then
if lspci 2>/dev/null | grep -E 'NVIDIA|AMD' > /dev/null; then
echo "GPU detected, installing CUDA packages"
uv pip install --python "$venv/bin/python" \
torch torchvision --index-url https://download.pytorch.org/whl/cu129
else
echo "No GPU detected, installing CPU packages"
uv pip install --python "$venv/bin/python" \
torch torchvision --index-url https://download.pytorch.org/whl/cpu
fi
touch "$FLOX_ENV_CACHE/.deps_installed"
fi
}
Complete CUDA Environment Examples
Basic CUDA Development
[install]
cuda_nvcc.pkg-path = "flox-cuda/cudaPackages_12_8.cuda_nvcc"
cuda_nvcc.priority = 1
cuda_nvcc.systems = ["aarch64-linux", "x86_64-linux"]
cuda_cudart.pkg-path = "flox-cuda/cudaPackages.cuda_cudart"
cuda_cudart.priority = 2
cuda_cudart.systems = ["aarch64-linux", "x86_64-linux"]
gcc.pkg-path = "gcc"
gcc-unwrapped.pkg-path = "gcc-unwrapped"
gcc-unwrapped.priority = 5
[vars]
CUDA_VERSION = "12.8"
CUDA_HOME = "$FLOX_ENV"
[hook]
echo "CUDA $CUDA_VERSION environment ready"
echo "nvcc: $(nvcc --version | grep release)"
Deep Learning with PyTorch
[install]
cuda_nvcc.pkg-path = "flox-cuda/cudaPackages_12_8.cuda_nvcc"
cuda_nvcc.priority = 1
cuda_nvcc.systems = ["aarch64-linux", "x86_64-linux"]
cuda_cudart.pkg-path = "flox-cuda/cudaPackages.cuda_cudart"
cuda_cudart.priority = 2
cuda_cudart.systems = ["aarch64-linux", "x86_64-linux"]
libcublas.pkg-path = "flox-cuda/cudaPackages_12_8.libcublas"
libcublas.priority = 2
libcublas.systems = ["aarch64-linux", "x86_64-linux"]
cudnn.pkg-path = "flox-cuda/cudaPackages_12_8.cudnn_9_11"
cudnn.priority = 2
cudnn.systems = ["aarch64-linux", "x86_64-linux"]
python313Full.pkg-path = "python313Full"
uv.pkg-path = "uv"
gcc-unwrapped.pkg-path = "gcc-unwrapped"
gcc-unwrapped.priority = 5
[vars]
CUDA_VERSION = "12.8"
PYTORCH_CUDA_ALLOC_CONF = "max_split_size_mb:128"
[hook]
setup_pytorch_cuda() {
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 "$FLOX_ENV_CACHE/.deps_installed" ]; then
uv pip install --python "$venv/bin/python" \
torch torchvision torchaudio \
--index-url https://download.pytorch.org/whl/cu129
touch "$FLOX_ENV_CACHE/.deps_installed"
fi
}
setup_pytorch_cuda
TensorFlow with CUDA
[install]
cuda_nvcc.pkg-path = "flox-cuda/cudaPackages_12_8.cuda_nvcc"
cuda_nvcc.priority = 1
cuda_nvcc.systems = ["aarch64-linux", "x86_64-linux"]
cuda_cudart.pkg-path = "flox-cuda/cudaPackages.cuda_cudart"
cuda_cudart.priority = 2
cuda_cudart.systems = ["aarch64-linux", "x86_64-linux"]
cudnn.pkg-path = "flox-cuda/cudaPackages_12_8.cudnn_9_11"
cudnn.priority = 2
cudnn.systems = ["aarch64-linux", "x86_64-linux"]
python313Full.pkg-path = "python313Full"
uv.pkg-path = "uv"
[hook]
setup_tensorflow() {
venv="$FLOX_ENV_CACHE/venv"
[ ! -d "$venv" ] && uv venv "$venv" --python python3
[ -f "$venv/bin/activate" ] && source "$venv/bin/activate"
if [ ! -f "$FLOX_ENV_CACHE/.tf_installed" ]; then
uv pip install --python "$venv/bin/python" tensorflow[and-cuda]
touch "$FLOX_ENV_CACHE/.tf_installed"
fi
}
setup_tensorflow
Multi-GPU Development
[install]
cuda_nvcc.pkg-path = "flox-cuda/cudaPackages_12_8.cuda_nvcc"
cuda_nvcc.priority = 1
cuda_nvcc.systems = ["aarch64-linux", "x86_64-linux"]
nccl.pkg-path = "flox-cuda/cudaPackages_12_8.nccl"
nccl.priority = 2
nccl.systems = ["aarch64-linux", "x86_64-linux"]
libcublas.pkg-path = "flox-cuda/cudaPackages_12_8.libcublas"
libcublas.priority = 2
libcublas.systems = ["aarch64-linux", "x86_64-linux"]
[vars]
CUDA_VISIBLE_DEVICES = "0,1,2,3" # All GPUs
NCCL_DEBUG = "INFO"
Modular CUDA Environments
Base CUDA Environment
# team/cuda-base
[install]
cuda_nvcc.pkg-path = "flox-cuda/cudaPackages_12_8.cuda_nvcc"
cuda_nvcc.priority = 1
cuda_nvcc.systems = ["aarch64-linux", "x86_64-linux"]
cuda_cudart.pkg-path = "flox-cuda/cudaPackages.cuda_cudart"
cuda_cudart.priority = 2
cuda_cudart.systems = ["aarch64-linux", "x86_64-linux"]
gcc.pkg-path = "gcc"
gcc-unwrapped.pkg-path = "gcc-unwrapped"
gcc-unwrapped.priority = 5
[vars]
CUDA_VERSION = "12.8"
CUDA_HOME = "$FLOX_ENV"
CUDA Math Libraries
# team/cuda-math
[include]
environments = [{ remote = "team/cuda-base" }]
[install]
libcublas.pkg-path = "flox-cuda/cudaPackages_12_8.libcublas"
libcublas.priority = 2
libcublas.systems = ["aarch64-linux", "x86_64-linux"]
libcufft.pkg-path = "flox-cuda/cudaPackages_12_8.libcufft"
libcufft.priority = 2
libcufft.systems = ["aarch64-linux", "x86_64-linux"]
libcurand.pkg-path = "flox-cuda/cudaPackages_12_8.libcurand"
libcurand.priority = 2
libcurand.systems = ["aarch64-linux", "x86_64-linux"]
CUDA Debugging Tools
# team/cuda-debug
[install]
cuda-gdb.pkg-path = "flox-cuda/cudaPackages_12_8.cuda-gdb"
cuda-gdb.systems = ["aarch64-linux", "x86_64-linux"]
nsight-systems.pkg-path = "flox-cuda/cudaPackages_12_8.nsight-systems"
nsight-systems.systems = ["aarch64-linux", "x86_64-linux"]
[vars]
CUDA_LAUNCH_BLOCKING = "1" # Synchronous kernel launches for debugging
Layer for Development
# Base CUDA environment
flox activate -r team/cuda-base
# Add debugging tools when needed
flox activate -r team/cuda-base -- flox activate -r team/cuda-debug
Testing CUDA Installation
Verify CUDA Compiler
nvcc --version
Check GPU Availability
nvidia-smi
Compile Test Program
cat > hello_cuda.cu << 'EOF'
#include <stdio.h>
__global__ void hello() {
printf("Hello from GPU!\n");
}
int main() {
hello<<<1,1>>>();
cudaDeviceSynchronize();
return 0;
}
EOF
nvcc hello_cuda.cu -o hello_cuda
./hello_cuda
Test PyTorch CUDA
import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")
print(f"GPU count: {torch.cuda.device_count()}")
if torch.cuda.is_available():
print(f"GPU name: {torch.cuda.get_device_name(0)}")
Best Practices
Always Use Priority Values
CUDA packages have predictable conflicts - assign explicit priorities
Version Consistency
Use specific versions (e.g., _12_8) for reproducibility. Don't mix CUDA versions.
Modular Design
Split base CUDA, math libs, and debugging into separate environments for flexibility
Test Compilation
Verify nvcc hello.cu -o hello works after setup
Platform Constraints
Always include systems = ["aarch64-linux", "x86_64-linux"]
Memory Management
Set appropriate CUDA memory allocator configs:
[vars]
PYTORCH_CUDA_ALLOC_CONF = "max_split_size_mb:128"
CUDA_LAUNCH_BLOCKING = "0" # Async by default
Common CUDA Gotchas
CUDA Toolkit ≠ Complete Toolkit
The cudatoolkit package doesn't include all libraries. Add what you need:
- libcublas for linear algebra
- libcufft for FFT
- cudnn for deep learning
License Conflicts
Every CUDA package may need explicit priority due to LICENSE file conflicts
No macOS Support
CUDA is Linux-only. Use Metal-accelerated packages on Darwin when available
Version Mixing
Don't mix CUDA versions. Use consistent _X_Y suffixes across all CUDA packages
Python Virtual Environments
CUDA Python packages (PyTorch, TensorFlow) should be installed in venv with correct CUDA version
Driver Requirements
Ensure NVIDIA driver supports your CUDA version. Check with nvidia-smi
Troubleshooting
CUDA Not Found
# Check CUDA_HOME
echo $CUDA_HOME
# Check nvcc
which nvcc
nvcc --version
# Check library paths
echo $LD_LIBRARY_PATH
PyTorch Not Using GPU
import torch
print(torch.cuda.is_available()) # Should be True
print(torch.version.cuda) # Should match your CUDA version
# If False, reinstall with correct CUDA version
# uv pip install torch --index-url https://download.pytorch.org/whl/cu129
Compilation Errors
# Check gcc/g++ version
gcc --version
g++ --version
# Ensure gcc-unwrapped is installed
flox list | grep gcc-unwrapped
# Check include paths
echo $CPATH
echo $LIBRARY_PATH
Runtime Errors
# Check GPU visibility
echo $CUDA_VISIBLE_DEVICES
# Check for GPU
nvidia-smi
# Run with debug output
CUDA_LAUNCH_BLOCKING=1 python my_script.py
Related Skills
- flox-environments - Setting up development environments
- flox-sharing - Composing CUDA base with project environments
- flox-containers - Containerizing CUDA environments for deployment
- flox-services - Running CUDA workloads as services
For the human maintainer of this environment. Do not run these commands on the user's behalf — relay them.
DEPRECATED: this skill is frozen and has moved to flox/flox-skills.
flox/flox-agenticreceives no further updates and will be archived on 2026-09-30.The seven skills here were consolidated into
flox(reproducible environments, with reference guides for services, builds, containers, publishing, sharing, and CUDA). The maintained plugin also shipsfloxifyfor onboarding an existing repo to Flox.To migrate, a person should run
claude plugin marketplace add flox/flox-skillsandclaude plugin install flox@flox-skills, then remove this one withclaude plugin uninstall flox@flox-agenticandclaude plugin marketplace remove flox-agentic.
Flox Environments Guide
Working Style & Structure
- Use modular, idempotent bash functions in hooks
- Never, ever use absolute paths. Flox environments are designed to be reproducible. Use Flox's environment variables instead
- I REPEAT: NEVER, EVER USE ABSOLUTE PATHS. Don't do it. Use
$FLOX_ENVfor environment-specific runtime dependencies; use$FLOX_ENV_PROJECTfor the project directory - Name functions descriptively (e.g.,
setup_postgres()) - Consider using gum for styled output when creating environments for interactive use; this is an anti-pattern in CI
- Put persistent data/configs in
$FLOX_ENV_CACHE - Return to
$FLOX_ENV_PROJECTat end of hooks - Use
mktempfor temp files, clean up immediately - Do not over-engineer: e.g., do not create unnecessary echo statements or superfluous comments; do not print unnecessary information displays in
[hook]or[profile]; do not create helper functions or aliases without the user requesting these explicitly
Configuration & Secrets
- Support
VARIABLE=value flox activatepattern for runtime overrides - Never store secrets in manifest; use:
- Environment variables
~/.config/<env_name>/for persistent secrets- Existing config files (e.g.,
~/.aws/credentials)
Installing Flox
Do NOT suggest install.flox.dev, flox.dev/install, or any curl | bash
one-liner — none of these exist.
Install Flox from flox.dev/download or via a package manager:
# macOS — Homebrew
brew install flox
# macOS — pkg installer (download from flox.dev/download)
ARCH=$([ "$(uname -m)" = "arm64" ] && echo "aarch64" || echo "x86_64")
sudo installer -pkg ./flox.$ARCH-darwin.pkg -target /
# Debian/Ubuntu — download .deb from flox.dev/download, then:
sudo apt install /path/to/flox.deb
# RPM (RedHat/CentOS/Amazon Linux) — download .rpm from flox.dev/download:
sudo rpm -ivh /path/to/flox.rpm
# Verify
flox --version
Flox Basics
- Flox is built on Nix; fully Nix-compatible
- Flox uses nixpkgs as its upstream; packages are usually named the same; unlike nixpkgs, Flox Catalog has millions of historical package-version combinations
- Key paths:
.flox/env/manifest.toml: Environment definition.flox/env.json: Environment metadata$FLOX_ENV_CACHE: Persistent, local-only storage (survivesflox delete)$FLOX_ENV_PROJECT: Project root directory (where .flox/ lives)$FLOX_ENV: basically the path to/usr: contains all the libs, includes, bins, configs, etc. available to a specific flox environment
- Always use
flox initto create environments - Manifest changes take effect on next
flox activate(not live reload)
Core Commands
flox init # Create new env
flox search <string> [--all] # Search for a package
flox show <pkg> # Show available historical versions of a package
flox install <pkg> # Add package
flox list [-e | -c | -n | -a] # List installed packages
flox activate # Enter env
flox activate -- <cmd> # Run without subshell
flox edit # Edit manifest interactively
Manifest Structure
[install]: Package list with descriptors[vars]: Static variables[hook]: Non-interactive setup scripts[profile]: Shell-specific functions/aliases[services]: Service definitions (see flox-services skill)[build]: Reproducible build commands (see flox-builds skill)[include]: Compose other environments (see flox-sharing skill)[options]: Activation mode, supported systems
The [install] Section
Package Installation Basics
The [install] table specifies packages to install.
[install]
ripgrep.pkg-path = "ripgrep"
pip.pkg-path = "python310Packages.pip"
Package Descriptors
Each entry has:
- Key: Install ID (e.g.,
ripgrep,pip) - your reference name for the package - Value: Package descriptor - specifies what to install
Catalog Descriptors (Most Common)
Options for packages from the Flox catalog:
[install]
example.pkg-path = "package-name" # Required: location in catalog
example.pkg-group = "mygroup" # Optional: group packages together
example.version = "1.2.3" # Optional: exact or semver range
example.systems = ["x86_64-linux"] # Optional: limit to specific platforms
example.priority = 3 # Optional: resolve file conflicts (lower = higher priority)
Key Options Explained:
pkg-path (required)
- Location in the package catalog
- Can be simple (
"ripgrep") or nested ("python310Packages.pip") - Can use array format:
["python310Packages", "pip"]
pkg-group
- Groups packages that work well together
- Packages without explicit group belong to default group
- Groups upgrade together to maintain compatibility
- Use different groups to avoid version conflicts
version
- Exact:
"1.2.3" - Semver ranges:
"^1.2",">=2.0" - Partial versions act as wildcards:
"1.2"= latest 1.2.X
systems
- Constrains package to specific platforms
- Options:
"x86_64-linux","x86_64-darwin","aarch64-linux","aarch64-darwin" - Defaults to manifest's
options.systemsif omitted
priority
- Resolves file conflicts between packages
- Default: 5
- Lower number = higher priority wins conflicts
- Critical for CUDA packages (see flox-cuda skill)
Practical Examples
# Platform-specific Python
[install]
python.pkg-path = "python311Full"
uv.pkg-path = "uv"
systems = ["x86_64-linux", "aarch64-linux"] # Linux only
# Version-pinned with custom priority
[nodejs]
nodejs.pkg-path = "nodejs"
version = "^20.0"
priority = 1 # Takes precedence in conflicts
# Multiple package groups to avoid conflicts
[install]
gcc.pkg-path = "gcc12"
gcc.pkg-group = "stable"
Language-Specific Patterns
Python Virtual Environments
venv creation pattern: Always check existence before activation:
if [ ! -d "$venv" ]; then
uv venv "$venv" --python python3
fi
# Guard activation - venv creation might not be complete
if [ -f "$venv/bin/activate" ]; then
source "$venv/bin/activate"
fi
Key patterns:
- venv location: Always use
$FLOX_ENV_CACHE/venv- survives environment rebuilds - uv with venv: Use
uv pip install --python "$venv/bin/python"NOT"$venv/bin/python" -m uv - Cache dirs: Set
UV_CACHE_DIRandPIP_CACHE_DIRto$FLOX_ENV_CACHEsubdirs - Dependency installation flag: Touch
$FLOX_ENV_CACHE/.deps_installedto prevent reinstalls
C/C++ Development
- Package Names:
gbenchmarknotbenchmark,catch2_3for Catch2,gcc13/clang_18for specific versions - System Constraints: Linux-only tools need explicit systems:
valgrind.systems = ["x86_64-linux", "aarch64-linux"] - Essential Groups: Separate
compilers,build,debug,testing,librariesgroups prevent conflicts - libstdc++ Access: ALWAYS include
gcc-unwrappedfor C++ stdlib headers/libs (gcc alone doesn't expose them):
gcc-unwrapped.pkg-path = "gcc-unwrapped"
gcc-unwrapped.priority = 5
gcc-unwrapped.pkg-group = "libraries"
Node.js Development
- Package managers: Install
nodejs(includes npm); addyarnorpnpmseparately if needed - Version pinning: Use
version = "^20.0"for LTS, or exact versions for reproducibility - Global tools pattern: Use
npxfor one-off tools, install commonly-used globals in manifest
Platform-Specific Patterns
# Darwin-specific frameworks
IOKit.pkg-path = "darwin.apple_sdk.frameworks.IOKit"
IOKit.systems = ["x86_64-darwin", "aarch64-darwin"]
# Platform-preferred compilers
gcc.pkg-path = "gcc"
gcc.systems = ["x86_64-linux", "aarch64-linux"]
clang.pkg-path = "clang"
clang.systems = ["x86_64-darwin", "aarch64-darwin"]
# Darwin GNU compatibility layer
coreutils.pkg-path = "coreutils"
coreutils.systems = ["x86_64-darwin", "aarch64-darwin"]
Best Practices
- Check manifest before installing new packages
- Use
returnnotexitin hooks - Define env vars with
${VAR:-default} - Use descriptive, prefixed function names in composed envs
- Cache downloads in
$FLOX_ENV_CACHE - Test activation with
flox activate -- <command>before adding to services - Use
--quietflag with uv/pip in hooks to reduce noise
Editing Manifests Non-Interactively
flox list -c > /tmp/manifest.toml
# Edit with sed/awk
flox edit -f /tmp/manifest.toml
Common Pitfalls
Hooks Run Every Activation
Hooks run EVERY activation (keep them fast/idempotent)
Hook vs Profile Functions
Hook functions are not available to users in the interactive shell; use [profile] for user-invokable commands/aliases
Profile Code in Layered Environments
Profile code runs for each layered/composed environment; keep auto-run display logic in [hook] to avoid repetition
Manifest Syntax Errors
Manifest syntax errors prevent ALL flox commands from working
Package Search Case Sensitivity
Package search is case-sensitive; use flox search --all for broader results
Troubleshooting Tips
Package Conflicts
If packages conflict, use different pkg-group values or adjust priority
Tricky Dependencies
- If we need
libstdc++, we get this from thegcc-unwrappedpackage, not fromgcc - If user is working with python and requests
uv, they typically do not meanuvicorn; clarify which package user wants
Hook Issues
- Use
returnnotexitin hooks - Define env vars with
${VAR:-default} - Guard FLOX_ENV_CACHE usage:
${FLOX_ENV_CACHE:-}with fallback
Environment Layering
What is Layering?
Layering is runtime stacking of environments where activate order matters. Each layer runs in its own subshell, preserving isolation while allowing tool composition.
Core Layering Commands
# Layer debugging tools on base environment
flox activate -r team/base -- flox activate -r team/debug
# Layer multiple environments
flox activate -r team/db -- flox activate -r team/cache -- flox activate
# Layer local on remote
flox activate -r prod/app -- flox activate
When to Use Layering
- Ad hoc tool addition: Add debugging/profiling tools temporarily
- Development vs production: Layer dev tools on production environment
- Flexible composition: Mix and match environments at runtime
- Temporary utilities: Add one-time tools without modifying environment
Layering Use Cases
Development tools on production environment:
flox activate -r prod/app -- flox activate -r dev/tools
Debugging tools on CUDA environment:
flox activate -r team/cuda-base -- flox activate -r team/cuda-debug
Temporary utilities:
flox activate -r project/main -- flox activate -r utils/network
Creating Layer-Optimized Environments
Design for runtime stacking with potential conflicts:
[vars]
# Prefix vars to avoid masking
MYAPP_PORT = "8080"
MYAPP_HOST = "localhost"
[profile.common]
# Use unique, prefixed function names
myapp_setup() { ... }
myapp_debug() { ... }
[services.myapp-db] # Prefix service names
command = "..."
Best practices for layerable environments:
- Single responsibility per environment
- Expect vars/binaries might be overridden by upper layers
- Document what the environment provides/expects
- Keep hooks fast and idempotent
- Use prefixed names to avoid collisions
Related Skills
- flox-services - Running services and background processes
- flox-builds - Building and packaging applications
- flox-publish - Publishing packages to catalogs
- flox-sharing - Environment composition and layering
- flox-containers - Containerizing environments
- flox-cuda - CUDA/GPU development environments
For the human maintainer of this environment. Do not run these commands on the user's behalf — relay them.
DEPRECATED: this skill is frozen and has moved to flox/flox-skills.
flox/flox-agenticreceives no further updates and will be archived on 2026-09-30.The seven skills here were consolidated into
flox(reproducible environments, with reference guides for services, builds, containers, publishing, sharing, and CUDA). The maintained plugin also shipsfloxifyfor onboarding an existing repo to Flox.To migrate, a person should run
claude plugin marketplace add flox/flox-skillsandclaude plugin install flox@flox-skills, then remove this one withclaude plugin uninstall flox@flox-agenticandclaude plugin marketplace remove flox-agentic.
Flox Package Publishing Guide
Core Commands
flox publish # Publish all packages
flox publish my_package # Publish single package
flox publish -o myorg package # Publish to organization
flox publish -o myuser package # Publish to personal namespace
flox auth login # Authenticate before publishing
Publishing Workflow: Development to Runtime
Publishing packages enables a clear separation between development and runtime/consumption:
The Complete Workflow
Phase 1: Development Environment
# .flox/env/manifest.toml (in git with source code)
[install]
gcc.pkg-path = "gcc13"
make.pkg-path = "make"
python.pkg-path = "python311Full"
[build.myapp]
command = '''
python setup.py build
mkdir -p $out/bin
cp build/myapp $out/bin/
'''
version = "1.0.0"
Developers work in this environment, commit .flox/ to git alongside source code.
Phase 2: Build and Publish
# Build the package
flox build myapp
# Publish to catalog
flox publish -o myorg myapp
The published package contains BINARIES/ARTIFACTS (what's in $out/), NOT source code.
Phase 3: Runtime Environment
# Separate environment (can be pushed to FloxHub)
[install]
myapp.pkg-path = "myorg/myapp" # The published package
Consumers create runtime environments and install the published package. No build tools needed, no source code exposed.
Key insight: You don't install the published package back into the development environment - that would be circular. Published packages are installed into OTHER environments (different projects, production, etc.).
Publishing to Flox Catalog
Prerequisites
Before publishing:
- Package defined in
[build]section or.flox/pkgs/ - Environment in Git repo with configured remote
- Clean working tree (no uncommitted changes)
- Current commit pushed to remote
- All build files tracked by Git
- At least one package installed in
[install]
Authentication
Run authentication before first publish:
flox auth login
Publishing Commands
# Publish single package
flox publish my_package
# Publish all packages
flox publish
# Publish to organization
flox publish -o myorg my_package
# Publish to personal namespace (for testing)
flox publish -o mypersonalhandle my_package
Catalog Types
Personal catalogs: Only visible to you (good for testing)
- Published to your personal namespace
- Example: User "alice" publishes "hello" → available as
alice/hello - Useful for testing before publishing to organization
Organization catalogs: Shared with team members (paid feature)
- Published to organization namespace
- Example: Org "acme" publishes "tool" → available as
acme/tool - All organization members can install
Build Validation
Flox clones your repo to a temp location and performs a clean build to ensure reproducibility. Only packages that build successfully in this clean environment can be published.
This validation ensures:
- All dependencies are declared
- Build is reproducible
- No reliance on local machine state
- Git repository is clean and up-to-date
After Publishing
- Package available in
flox search,flox show,flox install - Metadata sent to Flox servers
- Package binaries uploaded to Catalog Store
- Install with:
flox install <catalog>/<package>
Users can then:
# Search for your package
flox search my_package
# See package details
flox show myorg/my_package
# Install the package
flox install myorg/my_package
What Gets Published
Published packages contain:
- Binaries and compiled artifacts (everything in
$out/) - Runtime dependencies specified in
runtime-packages - Package metadata (version, description)
Published packages do NOT contain:
- Source code (unless explicitly copied to
$out/) - Build tools or build-time dependencies
- Development environment configuration
- The
.flox/directory itself
This separation allows you to share built artifacts without exposing source code.
Real-world Publishing Workflows
Application Development Workflow
Developer workflow:
-
Create development environment with build tools:
mkdir myapp && cd myapp flox init flox install gcc make python311Full -
Add source code and build definition to
.flox/env/manifest.toml:[build.myapp] command = '''make && cp myapp $out/bin/''' version = "1.0.0" -
Commit to git (environment definition + source code):
git add .flox/ src/ git commit -m "Add development environment and source" git push origin main -
Build and publish package (binaries/artifacts):
flox build myapp flox publish -o myorg myapp
Other developers:
- Clone repo:
git clone <repo> && cd myapp && flox activate - Get the same development environment with build tools
Consumers:
- Create new runtime environment:
flox init && flox install myorg/myapp - OR install into existing environment:
flox install myorg/myapp - Get the BUILT package (binaries), not source code
- Can push runtime environment to FloxHub without exposing source
Fork-based Development Pattern
- Fork upstream repo (e.g.,
user/projectfromupstream/project) - Add
.flox/to fork with build definitions - Commit and push:
git push origin main - Publish package:
flox publish -o username package-name - Others can install:
flox install username/package-name
Versioning Strategies
Semantic Versioning
[build.mytool]
version = "1.2.3" # Major.Minor.Patch
description = "My awesome tool"
Git-based Versioning
[build.mytool]
version.command = "git describe --tags"
description = "My awesome tool"
File-based Versioning
[build.mytool]
version.file = "VERSION.txt"
description = "My awesome tool"
Dynamic Versioning from Source
[build.rustapp]
version.command = "cargo metadata --no-deps --format-version 1 | jq -r '.packages[0].version'"
Publishing Multiple Variants
You can publish multiple variants of the same project:
[build.myapp]
command = '''
cargo build --release
mkdir -p $out/bin
cp target/release/myapp $out/bin/
'''
version = "1.0.0"
description = "Production build"
sandbox = "pure"
[build.myapp-debug]
command = '''
cargo build
mkdir -p $out/bin
cp target/debug/myapp $out/bin/myapp-debug
'''
version = "1.0.0"
description = "Debug build with symbols"
sandbox = "off"
Both can be published and users can choose which to install.
Testing Before Publishing
Local Testing
- Build the package:
flox build myapp
- Test the built artifact:
./result-myapp/bin/myapp --version
- Install locally to test:
flox install ./result-myapp
Personal Catalog Testing
Publish to your personal namespace first:
flox publish -o myusername myapp
Then test installation:
flox install myusername/myapp
Once validated, republish to organization:
flox publish -o myorg myapp
Common Gotchas
Branch names
Many repos use master not main - check with git branch
Auth required
Run flox auth login before first publish
Clean git state
Commit and push ALL changes before flox publish:
git status # Check for uncommitted changes
git add .flox/
git commit -m "Add flox build configuration"
git push origin master
runtime-packages
List only what package needs at runtime, not build deps:
[install]
gcc.pkg-path = "gcc"
make.pkg-path = "make"
[build.myapp]
command = '''make && cp myapp $out/bin/'''
runtime-packages = [] # No runtime deps needed
Git-tracked files only
All files referenced in build must be tracked:
git add .flox/pkgs/*
git add src/
git commit -m "Add build files"
Publishing Nix Expression Builds
For Nix expression builds in .flox/pkgs/:
- Create the Nix expression:
mkdir -p .flox/pkgs
cat > .flox/pkgs/hello.nix << 'EOF'
{ hello }:
hello.overrideAttrs (oldAttrs: {
patches = (oldAttrs.patches or []) ++ [ ./my.patch ];
})
EOF
- Track with Git:
git add .flox/pkgs/*
git commit -m "Add hello package"
git push
- Publish:
flox publish hello
Publishing Configuration and Assets
You can publish non-code artifacts:
Configuration templates
[build.nginx-config]
command = '''
mkdir -p $out/etc
cp nginx.conf $out/etc/
cp -r conf.d $out/etc/
'''
version = "1.0.0"
description = "Organization Nginx configuration"
Protocol buffers
[build.api-proto]
command = '''
mkdir -p $out/share/proto
cp proto/**/*.proto $out/share/proto/
'''
version = "2.1.0"
description = "API protocol definitions"
Teams install and reference via $FLOX_ENV/etc/ or $FLOX_ENV/share/.
Continuous Integration Publishing
GitHub Actions Example
name: Publish to Flox
on:
push:
tags:
- 'v*'
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Flox
run: |
curl -fsSL https://downloads.flox.dev/by-env/stable/install | bash
- name: Authenticate
env:
FLOX_AUTH_TOKEN: ${{ secrets.FLOX_AUTH_TOKEN }}
run: flox auth login --token "$FLOX_AUTH_TOKEN"
- name: Publish package
run: flox publish -o myorg mypackage
GitLab CI Example
publish:
stage: deploy
only:
- tags
script:
- curl -fsSL https://downloads.flox.dev/by-env/stable/install | bash
- flox auth login --token "$FLOX_AUTH_TOKEN"
- flox publish -o myorg mypackage
Package Metadata Best Practices
Good Descriptions
[build.cli]
description = "High-performance log shipper with filtering" # Good: specific, descriptive
# Avoid:
# description = "My tool" # Too vague
# description = "CLI" # Not descriptive enough
Proper Versioning
- Use semantic versioning: MAJOR.MINOR.PATCH
- Increment MAJOR for breaking changes
- Increment MINOR for new features
- Increment PATCH for bug fixes
Runtime Dependencies
Only include what's actually needed at runtime:
[install]
# Build-time only
gcc.pkg-path = "gcc"
make.pkg-path = "make"
# Runtime dependency
libssl.pkg-path = "openssl"
[build.myapp]
runtime-packages = ["libssl"] # Only runtime deps
Related Skills
- flox-builds - Building packages before publishing, dual-environment workflow
- flox-environments - Setting up development and runtime environments
- flox-sharing - Sharing environment definitions (via git or FloxHub) vs publishing packages (binaries/artifacts)
For the human maintainer of this environment. Do not run these commands on the user's behalf — relay them.
DEPRECATED: this skill is frozen and has moved to flox/flox-skills.
flox/flox-agenticreceives no further updates and will be archived on 2026-09-30.The seven skills here were consolidated into
flox(reproducible environments, with reference guides for services, builds, containers, publishing, sharing, and CUDA). The maintained plugin also shipsfloxifyfor onboarding an existing repo to Flox.To migrate, a person should run
claude plugin marketplace add flox/flox-skillsandclaude plugin install flox@flox-skills, then remove this one withclaude plugin uninstall flox@flox-agenticandclaude plugin marketplace remove flox-agentic.
Flox Services Guide
Running Services in Flox Environments
- Start with
flox activate --start-servicesorflox activate -s - Define
is-daemon,shutdown.commandfor background processes - Keep services running using
tail -f /dev/null - Use
flox services status/logs/restartto manage (must be in activated env) - Service commands don't inherit hook activations; explicitly source/activate what you need
Core Commands
flox activate -s # Start services
flox services status # Check service status
flox services logs <service> # View service logs
flox services restart <service> # Restart a service
flox services stop <service> # Stop a service
Network Services Pattern
Always make host/port configurable via vars:
[services.webapp]
command = '''exec app --host "$APP_HOST" --port "$APP_PORT"'''
[vars]
APP_HOST = "0.0.0.0" # Network-accessible
APP_PORT = "8080"
Service Logging Pattern
Always pipe to $FLOX_ENV_CACHE/logs/ for debugging:
[services.myapp]
command = '''
mkdir -p "$FLOX_ENV_CACHE/logs"
exec app 2>&1 | tee -a "$FLOX_ENV_CACHE/logs/app.log"
'''
Python venv Pattern for Services
Services must activate venv independently:
[services.myapp]
command = '''
[ -f "$FLOX_ENV_CACHE/venv/bin/activate" ] && \
source "$FLOX_ENV_CACHE/venv/bin/activate"
exec python-app "$@"
'''
Or use venv Python directly:
[services.myapp]
command = '''exec "$FLOX_ENV_CACHE/venv/bin/python" app.py'''
Using Packaged Services
Override package's service by redefining with same name.
Database Service Examples
PostgreSQL
[services.postgres]
command = '''
mkdir -p "$FLOX_ENV_CACHE/postgres"
if [ ! -d "$FLOX_ENV_CACHE/postgres/data" ]; then
initdb -D "$FLOX_ENV_CACHE/postgres/data"
fi
exec postgres -D "$FLOX_ENV_CACHE/postgres/data" \
-k "$FLOX_ENV_CACHE/postgres" \
-h "$POSTGRES_HOST" \
-p "$POSTGRES_PORT"
'''
is-daemon = true
[vars]
POSTGRES_HOST = "localhost"
POSTGRES_PORT = "5432"
POSTGRES_USER = "myuser"
POSTGRES_DB = "mydb"
Redis
[services.redis]
command = '''
mkdir -p "$FLOX_ENV_CACHE/redis"
exec redis-server \
--bind "$REDIS_HOST" \
--port "$REDIS_PORT" \
--dir "$FLOX_ENV_CACHE/redis"
'''
is-daemon = true
[vars]
REDIS_HOST = "127.0.0.1"
REDIS_PORT = "6379"
MongoDB
[services.mongodb]
command = '''
mkdir -p "$FLOX_ENV_CACHE/mongodb"
exec mongod \
--dbpath "$FLOX_ENV_CACHE/mongodb" \
--bind_ip "$MONGODB_HOST" \
--port "$MONGODB_PORT"
'''
is-daemon = true
[vars]
MONGODB_HOST = "127.0.0.1"
MONGODB_PORT = "27017"
Web Server Examples
Node.js Development Server
[services.dev-server]
command = '''
exec npm run dev -- --host "$DEV_HOST" --port "$DEV_PORT"
'''
[vars]
DEV_HOST = "0.0.0.0"
DEV_PORT = "3000"
Python Flask/FastAPI
[services.api]
command = '''
source "$FLOX_ENV_CACHE/venv/bin/activate"
exec python -m uvicorn main:app \
--host "$API_HOST" \
--port "$API_PORT" \
--reload
'''
[vars]
API_HOST = "0.0.0.0"
API_PORT = "8000"
Simple HTTP Server
[services.web]
command = '''exec python -m http.server "$WEB_PORT"'''
[vars]
WEB_PORT = "8000"
Environment Variable Convention
Use variables like POSTGRES_HOST, POSTGRES_PORT to define where services run.
These store connection details separately:
*_HOSTis the hostname or IP address (e.g.,localhost,db.example.com)*_PORTis the network port number (e.g.,5432,6379)
This pattern ensures users can override them at runtime:
POSTGRES_HOST=db.internal POSTGRES_PORT=6543 flox activate -s
Use consistent naming across services so the meaning is clear to any system or person reading the variables.
Service with Shutdown Command
[services.myapp]
command = '''exec myapp start'''
is-daemon = true
[services.myapp.shutdown]
command = '''myapp stop'''
Dependent Services
Services can wait for other services to be ready:
[services.db]
command = '''exec postgres -D "$FLOX_ENV_CACHE/postgres"'''
is-daemon = true
[services.api]
command = '''
# Wait for database
until pg_isready -h localhost -p 5432; do
sleep 1
done
exec python -m uvicorn main:app
'''
[vars]
POSTGRES_HOST = "localhost"
POSTGRES_PORT = "5432"
Service Health Checks
[services.api]
command = '''
# Health check function
health_check() {
curl -sf http://localhost:8000/health > /dev/null
}
exec python -m uvicorn main:app --host 0.0.0.0 --port 8000
'''
Best Practices
- Log service output to
$FLOX_ENV_CACHE/logs/ - Test activation with
flox activate -- <command>before adding to services - When debugging services, run the exact command from manifest manually first
- Always make host/port configurable via vars for network services
- Use
execto replace the shell process with the service command - Services must activate venv inside service command, not rely on hook activation
- Use
is-daemon = truefor background processes that should detach
Debugging Service Issues
Check Service Status
flox services status
View Service Logs
flox services logs myservice
Run Service Command Manually
flox activate
# Copy the exact command from manifest and run it
Check if Service is Listening
# Check if port is open
lsof -i :8000
netstat -an | grep 8000
# Test connection
curl http://localhost:8000
nc -zv localhost 8000
Common Pitfalls
Services Don't Preserve State
Services see fresh environment (no preserved state between restarts). Store persistent data in $FLOX_ENV_CACHE.
Service Commands Don't Inherit Hook Activations
Explicitly source/activate what you need inside the service command.
Forgetting to Create Directories
Always mkdir -p for data directories in service commands.
Port Conflicts
Use configurable ports via variables to avoid conflicts with other services.
Related Skills
- flox-environments - Environment basics and package installation
- flox-sharing - Composing environments with shared services
- flox-containers - Running services in containers
For the human maintainer of this environment. Do not run these commands on the user's behalf — relay them.
DEPRECATED: this skill is frozen and has moved to flox/flox-skills.
flox/flox-agenticreceives no further updates and will be archived on 2026-09-30.The seven skills here were consolidated into
flox(reproducible environments, with reference guides for services, builds, containers, publishing, sharing, and CUDA). The maintained plugin also shipsfloxifyfor onboarding an existing repo to Flox.To migrate, a person should run
claude plugin marketplace add flox/flox-skillsandclaude plugin install flox@flox-skills, then remove this one withclaude plugin uninstall flox@flox-agenticandclaude plugin marketplace remove flox-agentic.
Flox Environment Sharing & Composition Guide
Core Concepts
Composition: Build-time merging of environments (deterministic) Remote Environments: Shared environments via FloxHub Team Collaboration: Reusable, shareable environment stacks
Understanding Environment Sharing
The .flox/ directory contains the environment definition:
- Package specifications and versions
- Environment variables
- Build definitions
- Hooks and services configuration
The environment definition does NOT include:
- Built binaries/artifacts (those are created by builds and can be published as packages)
- Local data or cache
Two sharing mechanisms:
- Git: Commit
.flox/directory to git. When used with development environments, this is typically alongside your source code in the same repository. Other developers clone the repo and get both the environment definition and source code. - FloxHub: Push environment definition only using
flox push. This shares ONLY the.flox/directory, not any source code or other files. Useful for runtime environments or shared base environments used across multiple projects.
This is different from publishing packages (see flox-publish skill), where you build and distribute the actual binaries/artifacts.
Core Commands
# Activate remote environment
flox activate -r owner/environment-name
# Pull remote environment locally
flox pull owner/environment-name
# Push local environment to FloxHub
flox push
# Compose environments in manifest
# (see [include] section below)
Environment Composition
Basic Composition
Merge environments at build time using [include]:
[include]
environments = [
{ remote = "team/postgres" },
{ remote = "team/redis" },
{ remote = "team/python-base" }
]
Creating Composition-Optimized Environments
Design for clean merging at build time:
[install]
# Use pkg-groups to prevent conflicts
gcc.pkg-path = "gcc"
gcc.pkg-group = "compiler"
[vars]
# Never duplicate var names across composed envs
POSTGRES_PORT = "5432" # Not "PORT"
[hook]
# Check if setup already done (idempotent)
setup_postgres() {
[ -d "$FLOX_ENV_CACHE/postgres" ] || init_db
}
Best practices:
- No overlapping vars, services, or function names
- Use explicit, namespaced naming (e.g.,
postgres_initnotinit) - Minimal hook logic (composed envs run ALL hooks)
- Avoid auto-run logic in
[profile](runs once per layer/composition; help displays will repeat) - Test composability:
flox activateeach env standalone first
Composition Example: Full Stack
# .flox/env/manifest.toml
[include]
environments = [
{ remote = "team/postgres" },
{ remote = "team/redis" },
{ remote = "team/nodejs" },
{ remote = "team/monitoring" }
]
[vars]
# Override composed environment variables
POSTGRES_HOST = "localhost"
POSTGRES_PORT = "5433" # Non-standard port
Use Cases for Composition
Reproducible stacks:
[include]
environments = [
{ remote = "team/cuda-base" },
{ remote = "team/cuda-math" },
{ remote = "team/python-ml" }
]
Shared base configuration:
[include]
environments = [
{ remote = "org/standards" }, # Company-wide settings
{ remote = "team/backend" } # Team-specific tools
]
Creating Dual-Purpose Environments
Design for both layering and composition:
[install]
# Clear package groups
python.pkg-path = "python311"
python.pkg-group = "runtime"
[vars]
# Namespace everything
MYPROJECT_VERSION = "1.0"
MYPROJECT_CONFIG = "$FLOX_ENV_CACHE/config"
[profile.common]
# Defensive function definitions
if ! type myproject_init >/dev/null 2>&1; then
myproject_init() { ... }
fi
Remote Environments
Activating Remote Environments
# Activate remote environment directly
flox activate -r owner/environment-name
# Activate and run a command
flox activate -r owner/environment-name -- npm test
Pulling Remote Environments
# Pull to work on locally
flox pull owner/environment-name
# Now it's in your local .flox/
flox activate
Pushing Environments to FloxHub
# Initialize Git repo if needed
git init
git add .flox/
git commit -m "Initial environment"
# Push to FloxHub
flox push
# Others can now activate with:
# flox activate -r yourusername/your-repo
Choosing Between Git and FloxHub
Commit .flox/ to Git when:
- Environment is for development (includes build tools)
- Environment lives alongside source code
- You want version control history for environment changes
- Team already uses git for collaboration
Push to FloxHub when:
- Environment is for runtime/production (no source code needed)
- Creating shared base environments used across multiple projects
- Environment needs to be independently versioned from source code
- You want to share environment without exposing source code
Recommended pattern: Commit development environments to git with source code; push runtime environments to FloxHub.
Team Collaboration Patterns
Base + Specialization
Create base environment:
# team/base
[install]
git.pkg-path = "git"
gh.pkg-path = "gh"
jq.pkg-path = "jq"
[vars]
ORG_REGISTRY = "registry.company.com"
Specialize for teams:
# team/frontend
[include]
environments = [{ remote = "team/base" }]
[install]
nodejs.pkg-path = "nodejs"
pnpm.pkg-path = "pnpm"
# team/backend
[include]
environments = [{ remote = "team/base" }]
[install]
python.pkg-path = "python311Full"
uv.pkg-path = "uv"
Service Libraries
Create reusable service environments:
# team/postgres-service
[install]
postgresql.pkg-path = "postgresql"
[services.postgres]
command = '''
mkdir -p "$FLOX_ENV_CACHE/postgres"
if [ ! -d "$FLOX_ENV_CACHE/postgres/data" ]; then
initdb -D "$FLOX_ENV_CACHE/postgres/data"
fi
exec postgres -D "$FLOX_ENV_CACHE/postgres/data" \
-h "$POSTGRES_HOST" -p "$POSTGRES_PORT"
'''
is-daemon = true
[vars]
POSTGRES_HOST = "localhost"
POSTGRES_PORT = "5432"
Compose into projects:
# my-project
[include]
environments = [
{ remote = "team/postgres-service" },
{ remote = "team/redis-service" }
]
Development vs Runtime Environments
Development environment (for building):
# project-dev (committed to git with source code)
[install]
gcc.pkg-path = "gcc13"
make.pkg-path = "make"
debugpy.pkg-path = "python311Packages.debugpy"
pytest.pkg-path = "python311Packages.pytest"
[build.myapp]
command = '''
make release
mkdir -p $out/bin
cp build/myapp $out/bin/
'''
version = "1.0.0"
[vars]
DEBUG = "true"
LOG_LEVEL = "debug"
Developers commit this .flox/ directory to git with the source code. Other developers git clone and flox activate to get the same development environment.
Runtime environment (for consuming):
# project-runtime (pushed to FloxHub, no source code)
[install]
myapp.pkg-path = "myorg/myapp" # Published package, not source
[vars]
DEBUG = "false"
LOG_LEVEL = "info"
MYAPP_CONFIG = "$FLOX_ENV_CACHE/config"
After publishing myapp, consumers create this runtime environment and install the published package. The runtime environment can be pushed to FloxHub and shared without exposing source code.
Key distinction: Development environments contain build tools and source code; runtime environments contain published packages (binaries/artifacts).
(See flox-environments skill for layering environments at runtime)
Composition with Local Packages
Combine composed environments with local packages:
# Compose base services
[include]
environments = [
{ remote = "team/database-services" },
{ remote = "team/cache-services" }
]
# Add project-specific packages
[install]
myapp.pkg-path = "company/myapp"
See flox-environments skill for layering environments at runtime.
Best Practices
For Shareable Environments
- Use descriptive names:
team/postgres-servicenotdb - Document expectations: What vars/ports/services are provided
- Namespace everything: Prefix vars, functions, services
- Keep focused: One responsibility per environment
- Test standalone:
flox activateshould work without composition
For Composed Environments
- No name collisions: Check for overlapping vars/services
- Idempotent hooks: Can run multiple times safely
- Minimal auto-run: Avoid output in
[profile] - Clear dependencies: Document what environments are needed
(For layering best practices, see flox-environments skill)
Version Management
Pin Specific Versions
[include]
environments = [
{ remote = "team/base", version = "v1.2.3" }
]
Use Latest
[include]
environments = [
{ remote = "team/base" } # Uses latest
]
Troubleshooting
Conflicts in Composition
If composed environments conflict:
- Use different
pkg-groupvalues - Adjust
priorityfor file conflicts - Namespace variables to avoid collisions
- Test each environment standalone first
(For layering troubleshooting, see flox-environments skill)
Remote Environment Not Found
# Check available remote environments
flox search --remote owner/
# Pull and inspect locally
flox pull owner/environment-name
flox list -c
Related Skills
- flox-environments - Creating base environments
- flox-services - Sharing service configurations
- flox-containers - Deploying shared environments
- flox-publish - Publishing built packages (binaries/artifacts) vs sharing environments (definitions only)
Sponsors
Details
- Marketplace
- flox/flox-agentic
- Source
- flox-plugin
- Category
- Community
