CtrlK
BlogDocsLog inGet started
Tessl Logo

flox-services

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

86

Quality

81%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

SKILL.md
Quality
Evals
Security

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
Repository
flox/flox-agentic
Commit

32d3e1e

Last updated
Created

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill