Full Configuration Reference

Full Configuration Reference

flow8 has three configuration layers applied in order:

1. .env — environment variables loaded at startup
2. config/config.yml — YAML config with ${VAR} substitution via Viper
3. DBSystemConfig — database-level overrides (applied at runtime, no restart needed)

config/config.yml — Complete Schema

app:
  server:
    port: ${SERVER_PORT}          # HTTP listen port (default: 4454)
    url: ${API_URL}               # Base API URL for internal calls

channels:
  portRange: ${CHANNEL_PORT_RANGE} # Ports for channel runtimes (default: 7701-7799)

cors:
  debug: false
  allowedOrigins: ${ALLOWED_ORIGINS}          # Comma-separated allowed origins
  allowedMethods: [GET, POST, PUT, OPTIONS]
  allowedHeaders: [Accept, Authorization, Content-Type]
  allowCredentials: true

auth:
  session:
    cookie:
      domain: ${COOKIE_DOMAIN}    # Cookie domain (empty = current domain)
    lifeTime: 3600                # Session TTL in seconds
  oauth2:
    microsoft:
      endpoint:
        auth: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
        token: "https://login.microsoftonline.com/common/oauth2/v2.0/token"
        me: "https://graph.microsoft.com/v1.0/me"
      clientId: ${MICROSOFT_CLIENT_ID}
      clientSecret: ${MICROSOFT_CLIENT_SECRET}
      scope: ${MICROSOFT_SCOPE}
  external:
    jwt:
      secret: ${EXTERNAL_JWT_SECRET}
  salt:
    bytes: 32                     # Salt size for bcrypt password hashing

apps:
  autoregister:
    forceUpdate: ${APPS_FORCEUPDATE}   # Force module re-registration on startup
    create: ${APPS_AUTOCREATE}         # Auto-create missing module entries

api:
  meta:
    size:
      max: 100                    # Maximum page size for list endpoints
      default: 25                 # Default page size

output:
  ui:
    unitFieldMaxBytes: ${UNIT_OUTPUT_UI_MAX_BYTES}  # Max bytes per field in UI output display

audit:
  log:
    fieldMaxBytes: ${AUDIT_LOG_FIELD_MAX_BYTES}     # Max bytes per field in audit log entries

websocket:
  readDeadline: 30               # WS connection read timeout (seconds)
  pingPeriod: 15                 # WS ping interval (seconds)

alert:
  channel:
    email:
      from: ${ALERT_EMAIL_FROM}
      smtp:
        host: ${ALERT_EMAIL_HOST}
        port: ${ALERT_EMAIL_PORT}
        auth:
          user: ${ALERT_EMAIL_USER}
          pass: ${ALERT_EMAIL_PASS}

retention:
  default:
    cadence: ${RETENTION_DEFAULT_DAYS}     # Default retention duration (e.g., "30d")
    entries: ${RETENTION_DEFAULT_ENTRIES}  # Default max entries per flow
  cleanup:
    interval: ${RETENTION_CLEANUP_INTERVAL}         # Job run frequency (e.g., "2m")
    batchSize: ${RETENTION_CLEANUP_BATCH_SIZE}       # Records deleted per run
  enforcedMin:
    flows:
      cadence:
        all: ${RETENTION_ENFORCED_MIN_FLOWS_ALL_CADENCE}
        filtered: ${RETENTION_ENFORCED_MIN_FLOWS_FILTERED_CADENCE}
      entries: ${RETENTION_ENFORCED_MIN_FLOWS_ENTRIES}
    audit:
      cadence: ${RETENTION_ENFORCED_MIN_AUDIT_CADENCE}

caps:
  storage: ${CAPS_STORAGE}       # Enable file storage capability
  soffice: ${CAPS_SOFFICE}       # Enable LibreOffice conversion
  tesseract: ${CAPS_TESSERACT}   # Enable Tesseract OCR
  magick: ${CAPS_MAGICK}         # Enable ImageMagick processing

mcp:
  server:
    host: "localhost"
    port: 4445                   # MCP server port
  auth:
    jwt:
      secret: ${MCP_JWT_SECRET}

openai:
  api_key: ${OPENAI_API_KEY}
  generation:
    flow:
      limitPerDay: 100           # Max AI-generated flows per day per user

.config.yaml — Storage & Plugin Paths

path:
  in: "./drops"                              # Inbound drop location
  storage: "./storage"                       # Base storage directory
  tmp: "./storage/tmp"                       # Temporary processing files
  db: "./storage/db"                         # JSON database snapshots
  reserved: "./storage/reserved"
  out: "./storage/out"
  data:
    root: "./storage/data"                   # User data root
    files: "./storage/data/.files"           # Internal file storage
  logs: "./storage/logs"                     # Application log files
  plugins: "./pkg/plugins"                   # Plugin directory root
  soffice: "/Applications/LibreOffice.app/Contents/MacOS/soffice"  # LibreOffice binary

ext:
  supported: [".tiff", ".pdf", ".docx"]     # Allowed upload extensions
  excluded: [".DS_Store"]                   # Always rejected

qrcode:
  domain: "https://go.u8x.io/d/"           # QR code base URL

plugins:
  - "ad"                                    # Enabled plugin module names

DBSystemConfig — Runtime Overrides

The system_config MongoDB collection holds a single document per installation. Changes take effect immediately without a restart. Fields include:

• AI: default provider, model, and parameters
• Notification: email notification settings
• Retention: policy overrides that supplement .env values
• Execution: global execution settings (max concurrent plays, default timeout)

Query or update via the admin API or directly in MongoDB Express.

Viper Resolution

Viper resolves ${VAR_NAME} tokens in config/config.yml by looking up the environment variable VAR_NAME. If the variable is not set, the token is replaced with an empty string. Use .env to set values; they are auto-loaded at startup before Viper processes the YAML.