Skip to main content

​
Overview

Environment variables provide a convenient way to configure FastSkill without modifying code. They are especially useful for containerized deployments, CI/CD pipelines, and when configuration needs to be changed without code modifications.
Environment variables have lower priority than programmatic configuration. Use them for deployment-specific settings rather than core application behavior.

​
Configuration Variables

​
Core Configuration

​
FASTSKILL_LOG_LEVEL
string
Sets the minimum logging level for FastSkill operations. More verbose levels (DEBUG, TRACE) are useful for troubleshooting but may impact performance.
​
FASTSKILL_CONFIG_FILE
string
Path to a JSON configuration file that overrides default settings. Useful for complex configurations that are easier to manage in files.
​
FASTSKILL_STORAGE_PATH
string
Directory path where FastSkill looks for skill files and stores skill data. Can be absolute or relative to the working directory.

​
Execution Configuration

​
FASTSKILL_EXECUTION_TIMEOUT
integer
Default timeout in seconds for skill execution. Skills that take longer than this will be terminated.
​
FASTSKILL_MAX_MEMORY_MB
integer
Maximum memory in megabytes that a single skill execution can use. Helps prevent memory exhaustion.
​
FASTSKILL_MAX_CPU_PERCENT
integer
Maximum CPU usage percentage allowed for skill execution. Useful for preventing resource starvation in shared environments.
​
FASTSKILL_ENABLE_NETWORKING
boolean
Whether skills are allowed to make network requests. Set to false for enhanced security in production environments.
​
FASTSKILL_SANDBOX_LEVEL
string
Level of sandboxing for skill execution. strict provides maximum security but may limit functionality.

​
Performance Configuration

​
FASTSKILL_CACHE_SIZE
integer
Size of the metadata cache in number of entries. Larger values improve performance but use more memory.
​
FASTSKILL_CACHE_TTL
integer
Time-to-live for cache entries in seconds. Set to 0 to disable cache expiration.
​
FASTSKILL_ENABLE_CACHE_PERSISTENCE
boolean
Whether to persist cache to disk for faster startup times. Useful for production deployments.
​
FASTSKILL_CACHE_DIRECTORY
string
Directory path for persistent cache storage. If not set, uses system temporary directory.

​
Service Configuration

​
FASTSKILL_ENABLE_HOT_RELOAD
boolean
Enable automatic reloading of skills when files change. Useful during development but should be disabled in production.
​
FASTSKILL_WATCH_PATHS
string
Comma-separated list of directories to watch for skill changes. Only used when hot reload is enabled.
​
FASTSKILL_MAX_CONCURRENT_EXECUTIONS
integer
Maximum number of skill executions that can run simultaneously. Helps prevent resource exhaustion.
​
FASTSKILL_ENABLE_AUDIT_LOGGING
boolean
Enable detailed logging of all skill operations for security auditing and debugging.

​
Monitoring Configuration

​
FASTSKILL_ENABLE_METRICS
boolean
Enable collection of performance metrics for monitoring and optimization.
​
FASTSKILL_METRICS_RETENTION_HOURS
integer
Number of hours to retain performance metrics before automatic cleanup.
​
FASTSKILL_ENABLE_HEALTH_CHECKS
boolean
Enable health check endpoints for load balancers and monitoring systems.
​
FASTSKILL_HEALTH_CHECK_INTERVAL
integer
Interval in seconds between health checks when health checks are enabled.

​
Usage Examples

​
Development Setup

# Development environment variables
export FASTSKILL_LOG_LEVEL=DEBUG
export FASTSKILL_ENABLE_HOT_RELOAD=true
export FASTSKILL_WATCH_PATHS="./skills,./custom-skills"
export FASTSKILL_ENABLE_AUDIT_LOGGING=true
export FASTSKILL_CACHE_TTL=60

​
Production Setup

# Production environment variables
export FASTSKILL_LOG_LEVEL=INFO
export FASTSKILL_ENABLE_HOT_RELOAD=false
export FASTSKILL_EXECUTION_TIMEOUT=30
export FASTSKILL_MAX_MEMORY_MB=512
export FASTSKILL_ENABLE_NETWORKING=false
export FASTSKILL_SANDBOX_LEVEL=strict
export FASTSKILL_ENABLE_METRICS=true
export FASTSKILL_ENABLE_AUDIT_LOGGING=true

​
Docker Deployment

# Dockerfile
FROM fastskill:latest

# Set production configuration
ENV FASTSKILL_LOG_LEVEL=WARN
ENV FASTSKILL_STORAGE_PATH=/app/skills
ENV FASTSKILL_EXECUTION_TIMEOUT=60
ENV FASTSKILL_MAX_MEMORY_MB=1024
ENV FASTSKILL_ENABLE_HOT_RELOAD=false

# Run the application
CMD ["fastskill", "serve", "--host", "0.0.0.0"]

# docker-compose.yml
version: '3.8'
services:
  fastskill:
    image: fastskill:latest
    environment:
      - FASTSKILL_LOG_LEVEL=INFO
      - FASTSKILL_STORAGE_PATH=/app/skills
      - FASTSKILL_EXECUTION_TIMEOUT=30
      - FASTSKILL_MAX_MEMORY_MB=512
      - FASTSKILL_ENABLE_NETWORKING=false
      - FASTSKILL_SANDBOX_LEVEL=basic
    volumes:
      - ./skills:/app/skills:ro
    ports:
      - "8080:8080"

​
Kubernetes Deployment

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: fastskill
spec:
  replicas: 3
  selector:
    matchLabels:
      app: fastskill
  template:
    metadata:
      labels:
        app: fastskill
    spec:
      containers:
      - name: fastskill
        image: fastskill:latest
        env:
        - name: FASTSKILL_LOG_LEVEL
          value: "INFO"
        - name: FASTSKILL_STORAGE_PATH
          value: "/app/skills"
        - name: FASTSKILL_EXECUTION_TIMEOUT
          value: "30"
        - name: FASTSKILL_MAX_MEMORY_MB
          value: "512"
        - name: FASTSKILL_ENABLE_HOT_RELOAD
          value: "false"
        - name: FASTSKILL_ENABLE_METRICS
          value: "true"
        ports:
        - containerPort: 8080
        volumeMounts:
        - name: skills-volume
          mountPath: /app/skills
          readOnly: true
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "1Gi"
            cpu: "500m"
      volumes:
      - name: skills-volume
        configMap:
          name: skills-config

​
Priority Order

Configuration values are resolved in this order (highest to lowest priority):
  1. Programmatic Configuration: Values set in code using ServiceConfig
  2. Environment Variables: Values from environment variables
  3. Configuration Files: Values from JSON configuration files
  4. Default Values: Built-in default values
# Highest priority - programmatic configuration
config = ServiceConfig(
    execution_timeout=60,  # This overrides environment variables
    max_memory_mb=1024
)

# Environment variables (if programmatic config not set)
# export FASTSKILL_EXECUTION_TIMEOUT=30
# export FASTSKILL_MAX_MEMORY_MB=512

# Configuration file (if no env vars)
# {
#   "execution_timeout": 30,
#   "max_memory_mb": 512
# }

# Default values (if nothing else set)
# execution_timeout: 30
# max_memory_mb: 256

​
Validation

FastSkill validates environment variables at startup: 
import os
from fastskill import ServiceConfig

# Check for invalid values
try:
    config = ServiceConfig.from_env()
    config.validate()
    print("✅ Environment configuration is valid")
except ValueError as e:
    print(f"❌ Configuration error: {e}")

​
Common Validation Errors

Invalid numeric values: Ensure numeric environment variables contain valid numbers
# ❌ Invalid
export FASTSKILL_EXECUTION_TIMEOUT=abc

# ✅ Valid
export FASTSKILL_EXECUTION_TIMEOUT=30
Invalid boolean values: Boolean environment variables must be “true” or “false” (case insensitive)
# ❌ Invalid
export FASTSKILL_ENABLE_HOT_RELOAD=1

# ✅ Valid
export FASTSKILL_ENABLE_HOT_RELOAD=true
Invalid enum values: Enum values must match exactly (case sensitive)
# ❌ Invalid
export FASTSKILL_LOG_LEVEL=info

# ✅ Valid
export FASTSKILL_LOG_LEVEL=INFO

​
Best Practices

1

Use for deployment-specific settings

Use environment variables for settings that change between environments (development, staging, production).
2

Don't commit secrets

Never put sensitive information like API keys or passwords in environment variables in version control.
3

Document your variables

Maintain documentation of which environment variables are used and their expected values.
4

Use consistent naming

Follow the FASTSKILL_ prefix convention for all FastSkill-related environment variables.
5

Validate in CI/CD

Add validation steps in your deployment pipeline to catch configuration errors early.

​
Migration from Configuration Files

If you’re migrating from configuration files to environment variables:
1

Map configuration to variables

# config.json
{
  "execution": {
    "default_timeout": 30,
    "max_memory_mb": 512
  },
  "enable_hot_reload": true
}

# Environment variables
export FASTSKILL_EXECUTION_TIMEOUT=30
export FASTSKILL_MAX_MEMORY_MB=512
export FASTSKILL_ENABLE_HOT_RELOAD=true
2

Update deployment scripts

Replace configuration file references with environment variable exports in your deployment scripts.
3

Test thoroughly

Test the migration in a staging environment to ensure all variables are properly set and validated.

​
Troubleshooting

Caching: Some configuration changes require service restart to take effect. Check if your service supports hot reloading.
Priority: Remember that programmatic configuration overrides environment variables. Check your code for explicit configuration.
Validation: Use the validation methods to check if your environment variables are being parsed correctly.
Environment Variable Security: In most systems, environment variables are visible to all processes running as the same user. Consider using configuration files for sensitive settings in multi-user environments.
Container Security: In Docker and Kubernetes, environment variables are included in container inspection output. Use secrets management for sensitive values.
Windows: Use set instead of export for setting environment variables in Command Prompt.
Case Sensitivity: Environment variable names are case-sensitive on most Unix systems but case-insensitive on Windows.
Environment variables provide flexibility for deployment but should be used thoughtfully. For complex applications, consider using configuration files for better visibility and version control integration.