Connector Config File Reference

This document provides a complete reference for the connector configuration file format used by AxonFlow.

File Location

AxonFlow looks for config files in this order:

1. AXONFLOW_CONFIG_FILE environment variable (if set)
2. ./axonflow.yaml (current directory)
3. ./config/axonflow.yaml
4. /etc/axonflow/axonflow.yaml

Set the config file path:

export AXONFLOW_CONFIG_FILE=/path/to/axonflow.yaml

Supported formats: YAML (.yaml, .yml) and JSON (.json)

Basic Structure

# Root-level settings
version: "1.0"

# Connector definitions (map format - name is the key)
connectors:
  my_postgres:                # Connector name (unique identifier)
    type: postgres            # Required: connector type
    enabled: true             # Optional: default true
    display_name: "My Database"
    description: "Primary PostgreSQL database"
    connection_url: postgres://localhost:5432/mydb
    credentials:              # Authentication credentials
      username: myuser
      password: mypassword
    options:                  # Type-specific options
      max_open_conns: 10
    timeout_ms: 30000         # Default: 30000 (30 seconds)
    max_retries: 3            # Default: 3

# LLM providers (can be in same file)
llm_providers:
  openai:
    enabled: true
    credentials:
      api_key: ${OPENAI_API_KEY}

Common Fields

All connectors support these fields:

Field	Type	Required	Description
type	string	Yes	Connector type (postgres, mysql, mongodb, redis, http, cassandra, etc.)
enabled	boolean	No	Whether connector is active (default: true)
display_name	string	No	Human-readable name for UI
description	string	No	Description of the connector
connection_url	string	No	Connection URL (type-specific)
credentials	object	No	Authentication credentials
options	object	No	Type-specific configuration options
timeout_ms	integer	No	Timeout in milliseconds (default: 30000)
max_retries	integer	No	Retry count (default: 3)
tenant_id	string	No	Tenant identifier for multi-tenant setups

Environment Variable Expansion

Config files support environment variable expansion with ${VAR_NAME} syntax:

connectors:
  production_db:
    type: postgres
    enabled: true
    connection_url: ${DATABASE_URL}
    credentials:
      username: ${POSTGRES_USER:-postgres}  # Default value if not set
      password: ${POSTGRES_PASSWORD}

Connector Type Reference

PostgreSQL

connectors:
  customer_db:
    type: postgres
    enabled: true
    display_name: "Customer Database"
    connection_url: postgres://localhost:5432/customers
    credentials:
      username: ${POSTGRES_USER:-postgres}
      password: ${POSTGRES_PASSWORD}
    options:
      max_open_conns: 10
      max_idle_conns: 5
      conn_max_lifetime: "5m"
      ssl_mode: require    # disable, require, verify-ca, verify-full
    timeout_ms: 30000
    max_retries: 3

MySQL

connectors:
  orders_db:
    type: mysql
    enabled: true
    connection_url: mysql://mysql.example.com:3306/orders
    credentials:
      username: reader
      password: ${MYSQL_PASSWORD}
    options:
      max_open_conns: 10
      charset: utf8mb4
      collation: utf8mb4_unicode_ci
      tls_enabled: true

MongoDB

connectors:
  documents_db:
    type: mongodb
    enabled: true
    connection_url: mongodb://mongodb.example.com:27017/documents
    credentials:
      username: appuser
      password: ${MONGO_PASSWORD}
    options:
      auth_source: admin
      replica_set: rs0
      max_pool_size: 10

Redis

connectors:
  cache:
    type: redis
    enabled: true
    connection_url: redis://redis.example.com:6379
    credentials:
      password: ${REDIS_PASSWORD}
    options:
      db: 0
      pool_size: 10
      dial_timeout: "5s"

Cassandra

connectors:
  timeseries_db:
    type: cassandra
    enabled: true
    credentials:
      username: appuser
      password: ${CASSANDRA_PASSWORD}
    options:
      hosts:
        - cassandra1.example.com
        - cassandra2.example.com
      port: 9042
      keyspace: analytics
      consistency: LOCAL_QUORUM

HTTP

connectors:
  external_api:
    type: http
    enabled: true
    connection_url: https://api.example.com
    credentials:
      api_key: ${API_KEY}
    options:
      auth_type: bearer    # none, basic, bearer, api_key
      api_key_header: X-API-Key
      headers:
        User-Agent: AxonFlow/1.0
        Accept: application/json

S3

connectors:
  data_lake:
    type: s3
    enabled: true
    credentials:
      access_key_id: ${AWS_ACCESS_KEY_ID}
      secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    options:
      region: us-east-1
      bucket: my-data-bucket
      prefix: data/
      # use_iam_role: true  # Alternative: use IAM role

Azure Blob Storage

connectors:
  azure_storage:
    type: azure_blob
    enabled: true
    credentials:
      account_key: ${AZURE_STORAGE_KEY}
    options:
      account_name: mystorageaccount
      container: mycontainer
      prefix: data/

Google Cloud Storage

connectors:
  gcs_storage:
    type: gcs
    enabled: true
    credentials:
      credentials_file: /path/to/service-account.json
    options:
      project_id: my-project
      bucket: my-bucket
      prefix: data/

Full Example

# axonflow.yaml - Complete configuration example
version: "1.0"

connectors:
  # Primary PostgreSQL database
  primary_db:
    type: postgres
    enabled: true
    display_name: "Primary Database"
    description: "Main production PostgreSQL database"
    connection_url: ${DATABASE_URL}
    credentials:
      username: ${POSTGRES_USER:-app_user}
      password: ${POSTGRES_PASSWORD}
    options:
      max_open_conns: 20
      ssl_mode: require
    timeout_ms: 30000
    max_retries: 3

  # Redis cache
  cache:
    type: redis
    enabled: true
    display_name: "Redis Cache"
    connection_url: redis://${REDIS_HOST}:6379
    credentials:
      password: ${REDIS_PASSWORD}
    options:
      db: 0
      pool_size: 15

  # External API integration
  payment_api:
    type: http
    enabled: true
    display_name: "Payment API"
    connection_url: https://api.payments.example.com
    credentials:
      api_key: ${PAYMENT_API_TOKEN}
    options:
      auth_type: bearer
      headers:
        X-Client-Version: "1.0"
    timeout_ms: 10000

  # S3 for document storage
  documents:
    type: s3
    enabled: true
    display_name: "Document Storage"
    credentials:
      access_key_id: ${AWS_ACCESS_KEY_ID}
      secret_access_key: ${AWS_SECRET_ACCESS_KEY}
    options:
      region: us-east-1
      bucket: company-documents
      prefix: uploads/

  # Disabled connector (available but not active)
  legacy_db:
    type: mysql
    enabled: false
    display_name: "Legacy Database"
    connection_url: mysql://legacy-mysql.example.com:3306/legacy
    credentials:
      username: readonly
      password: ${LEGACY_DB_PASSWORD}

# LLM Providers (optional - can be in same file)
llm_providers:
  openai:
    enabled: true
    display_name: "OpenAI GPT-4"
    credentials:
      api_key: ${OPENAI_API_KEY}
    config:
      model: gpt-4o
      max_tokens: 4096
    priority: 10
    weight: 0.5

  anthropic:
    enabled: true
    display_name: "Anthropic Claude"
    credentials:
      api_key: ${ANTHROPIC_API_KEY}
    config:
      model: claude-sonnet-4-20250514
      max_tokens: 8192
    priority: 10
    weight: 0.5

  ollama:
    enabled: false
    display_name: "Ollama (Local)"
    config:
      endpoint: http://localhost:11434
      model: llama3.2:latest
    priority: 5
    weight: 0.3

Validation

Validate your config file before deployment:

# YAML syntax validation
python3 -c "import yaml; yaml.safe_load(open('axonflow.yaml'))"

# JSON syntax validation
python3 -c "import json; json.load(open('axonflow.json'))"

Common Validation Errors

Below are common configuration mistakes and how to fix them.

Missing Required Field: type

Error:

connector "my_db": missing required field "type"

Cause: Every connector entry must include a type field.

Fix:

connectors:
  my_db:
    type: postgres    # <-- add this
    connection_url: postgres://localhost:5432/mydb

Invalid Environment Variable Reference

Error:

connector "production_db": unresolved variable "${POSTGRES_PASSWORD}"

Cause: The environment variable is not set at runtime.

Fix: Either set the variable before starting AxonFlow or provide a default:

credentials:
  password: ${POSTGRES_PASSWORD:-default_password}  # Default value with :-

Duplicate Connector Names

Error:

duplicate connector name "cache" at line 42

Cause: Two connectors share the same YAML key.

Fix: Use unique names for each connector:

connectors:
  cache_primary:     # unique name
    type: redis
    connection_url: redis://primary:6379
  cache_replica:     # unique name
    type: redis
    connection_url: redis://replica:6379

Invalid YAML Syntax (Indentation)

Error:

yaml: line 15: did not find expected key

Cause: Incorrect indentation or mixing tabs and spaces.

Fix: Use consistent 2-space indentation throughout the file. Never use tabs. Ensure nested keys are properly indented:

connectors:
  my_db:           # 2-space indent
    type: postgres # 4-space indent
    credentials:   # 4-space indent
      username: user  # 6-space indent

Connection URL with Special Characters

Error:

connector "my_db": invalid connection URL

Cause: Passwords containing special characters (@, #, %, etc.) in the URL are not URL-encoded.

Fix: URL-encode special characters in the connection string, or use separate credential fields:

connectors:
  my_db:
    type: postgres
    # Option 1: URL-encode special chars (@ becomes %40)
    connection_url: postgres://user:p%40ssw0rd@localhost:5432/mydb
    # Option 2: Use separate credentials (recommended)
    credentials:
      username: user
      password: "p@ssw0rd"  # Quote values with special chars

Hot Reload

Config file changes can be applied without restart (30-second cache TTL):

1. Update the config file
2. Wait for automatic reload (30 seconds), OR
3. Call the refresh API for immediate effect:

   curl -X POST https://agent.example.com/api/v1/connectors/refresh

The agent reloads configurations and recreates connector instances on next use.

Related Documentation

• Runtime Configuration - Dynamic configuration overview
• MCP Connectors Overview - Connector types and capabilities
• Connector SDK - Building custom connectors