Configuration

Flowgen reads a single YAML file (passed via --config). Top-level sections:

flows:             # Flow discovery (required).
cache:             # Distributed cache backend (optional).
resources:         # External resource loading (optional).
http_server:       # Webhook / metrics HTTP server (optional).
mcp_server:        # MCP server for tools/resources/prompts (optional).
ai_gateway:        # OpenAI-compatible LLM gateway (optional).
web:               # Web UI (optional).
health:            # k8s liveness/readiness listener (defaults on).
retry:             # Default retry policy for every task (optional).
telemetry:         # OpenTelemetry export (optional).

Only flows is required. Every other section has working defaults.

Minimal config

flows:
  path: /etc/flowgen/flows/

Discovers every .yaml/.yml/.json file under the path and runs them with an in-memory cache, no resources directory, no HTTP server, and no telemetry.

Full reference

flows:
  path: /etc/flowgen/flows/
  cache:
    enabled: true
    prefix: flows
    db_name: flowgen_system

cache:
  enabled: true
  type: nats
  credentials_path: /etc/nats/credentials.json
  url: "{{env.NATS_URL}}"
  runtime:
    db_name: flowgen_cache
  system:
    db_name: flowgen_system
  history: 10
  tombstone_ttl: "1h"

resources:
  path: /etc/flowgen/resources/

http_server:
  enabled: true
  port: 3000
  path: /api/flowgen/workers/v1
  credentials_path: /etc/flowgen/credentials/http.json
  auth:
    type: jwt
    secret: "shared-secret"

mcp_server:
  enabled: true
  port: 3001
  path: /mcp/v1
  credentials_path: /etc/flowgen/credentials/mcp.json

ai_gateway:
  enabled: true
  port: 3002
  path: /v1
  credentials_path: /etc/flowgen/credentials/ai.json

web:
  enabled: true
  port: 8080
  path: /flowgen
  headers:
    X-Flowgen-Client: flowgen-ui

health:
  enabled: true
  port: 8081

retry:
  max_attempts: 10
  initial_backoff: "1s"

telemetry:
  enabled: true
  backend:
    type: remote
    endpoint: http://otel-collector:4317
  service_name: flowgen
  metrics_export_interval: "60s"

flows

Flow discovery. Filesystem and distributed cache can be used independently or together; flowgen merges flows from both sources at startup.

Both sources can be active at the same time. Use this for gradual migration: a small set of bootstrap flows mounted from disk (typically a sync flow that pulls user flows from Git into the cache), with the bulk of user flows loaded from the cache. On a name collision the filesystem entry wins, so a locally mounted bootstrap flow cannot be silently overridden by a stale cache entry.

Cache-mode flow loading is useful when flows are provisioned dynamically — for example, a control plane writes flow YAML into NATS KV and every flowgen replica picks them up.

cache

Distributed cache backend. When omitted, flowgen uses an in-memory cache (single-node only).

If NATS is configured but unreachable, flowgen falls back to in-memory automatically and logs a warning. See Caching.

resources

External resource loading for SQL queries, prompts, scripts, schemas. See Resources.

When resources is omitted, only inline content is supported — any task that uses { resource: ... } will fail at startup with a clear error.

http_server

HTTP server that hosts every http_endpoint route plus health/metrics endpoints.

mcp_server

MCP server for exposing mcp_tool, mcp_resource, and mcp_prompt tasks to LLM clients.

ai_gateway

OpenAI-compatible LLM gateway that serves every registered llm_proxy flow.

web

Embedded web dashboard and JSON API.

The API contract is defined in openapi.yaml and served at <path>/api/openapi.yaml.

Conversations from flows

With web.auth, each signed-in user sees their own conversations and the shared ones; without it, every conversation is shared.

A flow opens a conversation in the Agents tab by writing it to the system bucket (cache.system.db_name) with nats_kv_store. Under agents.conversations.<id> it is shared. Under agents.conversations.<user>.<id>, where <user> is the hex SHA-256 of the user id, only that user sees it; a flow started by an http_endpoint or mcp_tool with auth has the id in event.meta.auth.user_id, so a script gets <user> with sha256(event.meta.auth.user_id). The id uses only letters, digits, - and _. event.data.content is a Conversation from openapi.yaml as JSON, with origin: agent and unread: true, and optionally folder, e.g. Preflight/Klaviyo. It is unread for each user until they open it, and again when it changes. Marking a conversation read or unread, or moving it to another folder, affects only the user who does it; without web.auth it affects everyone.

- nats_kv_store:
    name: open_conversation
    url: "{{env.NATS_URL}}"
    bucket: flowgen_system
    operation: put
    key: "agents.conversations.{{event.meta.correlation_id}}"
    ttl: 30d

health

Kubernetes liveness/readiness listener.

retry

Sets the default retry policy for every task. Individual tasks can override via their own retry field.

See Retry for how events, task startup, subscribers and flow restarts retry.

telemetry

OpenTelemetry providers for metrics, traces, and logs. See Telemetry.

When telemetry is omitted entirely, no telemetry stack is started.

Running

flowgen --config /etc/flowgen/config.yaml

Flowgen validates the config at startup. Any field with a typo, missing required value, or invalid type produces an error before any flow runs.