flox-services

name	flox-services
description	Running services and background processes in Flox environments. Use for service configuration, network services, logging, database setup, and service debugging.

Flox Services Guide

Running Services in Flox Environments

• Start with flox activate --start-services or flox activate -s
• Define is-daemon, shutdown.command for background processes
• Keep services running using tail -f /dev/null
• Use flox services status/logs/restart to 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:

• *_HOST is the hostname or IP address (e.g., localhost, db.example.com)
• *_PORT is 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 exec to replace the shell process with the service command
• Services must activate venv inside service command, not rely on hook activation
• Use is-daemon = true for 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