flox-sharing

What this skill does

# 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**:
1. **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.
2. **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

```bash
# 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]`:

```toml
[include]
environments = [
    { remote = "team/postgres" },
    { remote = "team/redis" },
    { remote = "team/python-base" }
]
```

### Creating Composition-Optimized Environments

**Design for clean merging at build time:**

```toml
[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_init` not `init`)
- 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 activate` each env standalone first

### Composition Example: Full Stack

```toml
# .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:**
```toml
[include]
environments = [
    { remote = "team/cuda-base" },
    { remote = "team/cuda-math" },
    { remote = "team/python-ml" }
]
```

**Shared base configuration:**
```toml
[include]
environments = [
    { remote = "org/standards" },  # Company-wide settings
    { remote = "team/backend" }    # Team-specific tools
]
```

## Creating Dual-Purpose Environments

**Design for both layering and composition:**

```toml
[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

```bash
# 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

```bash
# Pull to work on locally
flox pull owner/environment-name

# Now it's in your local .flox/
flox activate
```

### Pushing Environments to FloxHub

```bash
# 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:**
```toml
# team/base
[install]
git.pkg-path = "git"
gh.pkg-path = "gh"
jq.pkg-path = "jq"

[vars]
ORG_REGISTRY = "registry.company.com"
```

**Specialize for teams:**
```toml
# team/frontend
[include]
environments = [{ remote = "team/base" }]

[install]
nodejs.pkg-path = "nodejs"
pnpm.pkg-path = "pnpm"
```

```toml
# team/backend
[include]
environments = [{ remote = "team/base" }]

[install]
python.pkg-path = "python311Full"
uv.pkg-path = "uv"
```

### Service Libraries

**Create reusable service environments:**

```toml
# 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:**
```toml
# my-project
[include]
environments = [
    { remote = "team/postgres-service" },
    { remote = "team/redis-service" }
]
```

### Development vs Runtime Environments

**Development environment (for building):**
```toml
# 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):**
```toml
# 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:

```toml
# 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 Environme