Configuration guide

This guide explains the unified configuration system available in SignalWire AI Agents SDK.

Overview

All SignalWire services (SWML, Search, MCP Gateway) now support optional JSON configuration files with environment variable substitution. Services continue to work without any configuration file, maintaining full backward compatibility.

Quick start

Zero configuration (default)

# Works exactly as before - no config needed
agent = MyAgent()
agent.run()

With configuration file

# Automatically detects config.json if present
agent = MyAgent()

# Or specify a config file
agent = MyAgent(config_file="production_config.json")

Configuration files

File locations

Services look for configuration files in this order:

1. Service-specific: {service_name}_config.json (e.g., search_config.json)
2. Generic: config.json
3. Hidden: .swml/config.json
4. User home: ~/.swml/config.json
5. System: /etc/swml/config.json

Configuration structure

{
  "service": {
    "name": "my-service",
    "host": "${HOST|0.0.0.0}",
    "port": "${PORT|3000}"
  },
  "security": {
    "ssl_enabled": "${SSL_ENABLED|false}",
    "ssl_cert_path": "${SSL_CERT|/etc/ssl/cert.pem}",
    "ssl_key_path": "${SSL_KEY|/etc/ssl/key.pem}",
    "auth": {
      "basic": {
        "enabled": true,
        "user": "${AUTH_USER|signalwire}",
        "password": "${AUTH_PASSWORD}"
      },
      "bearer": {
        "enabled": "${BEARER_ENABLED|false}",
        "token": "${BEARER_TOKEN}"
      }
    },
    "allowed_hosts": ["${PRIMARY_HOST}", "${SECONDARY_HOST|localhost}"],
    "cors_origins": "${CORS_ORIGINS|*}",
    "rate_limit": "${RATE_LIMIT|60}"
  }
}

Environment variable substitution

The configuration system supports ${VAR|default} syntax:

• ${VAR} - Use environment variable VAR (error if not set)
• ${VAR|default} - Use VAR or "default" if not set
• ${VAR|} - Use VAR or empty string if not set

Examples

{
  "database": {
    "host": "${DB_HOST|localhost}",
    "port": "${DB_PORT|5432}",
    "password": "${DB_PASSWORD}"
  }
}

Priority order

Configuration values are applied in this order (highest to lowest):

1. Constructor parameters - Explicitly passed to service
2. Config file values - From JSON configuration
3. Environment variables - Direct env vars (backward compatibility)
4. Defaults - Hard-coded defaults

Service-specific configuration

SWML/Agent configuration

{
  "service": {
    "name": "my-agent",
    "route": "/agent",
    "port": "${AGENT_PORT|3000}"
  },
  "security": {
    "ssl_enabled": "${SSL_ENABLED|false}",
    "auth": {
      "basic": {
        "user": "${AGENT_USER|agent}",
        "password": "${AGENT_PASSWORD}"
      }
    }
  }
}

Search service configuration

{
  "service": {
    "port": "${SEARCH_PORT|8001}",
    "indexes": {
      "docs": "${DOCS_INDEX|./docs.swsearch}",
      "api": "${API_INDEX|./api.swsearch}"
    }
  },
  "security": {
    "ssl_enabled": "${SEARCH_SSL|false}",
    "auth": {
      "basic": {
        "enabled": true,
        "user": "${SEARCH_USER|search}",
        "password": "${SEARCH_PASSWORD}"
      }
    }
  }
}

MCP Gateway configuration

{
  "server": {
    "host": "${MCP_HOST|0.0.0.0}",
    "port": "${MCP_PORT|8080}",
    "auth_user": "${MCP_USER|admin}",
    "auth_password": "${MCP_PASSWORD}",
    "auth_token": "${MCP_TOKEN}"
  },
  "services": {
    "example": {
      "command": ["python", "${SERVICE_PATH|./service.py}"],
      "enabled": "${SERVICE_ENABLED|true}"
    }
  },
  "session": {
    "default_timeout": "${SESSION_TIMEOUT|300}",
    "max_sessions_per_service": "${MAX_SESSIONS|100}"
  }
}

Security configuration

All services share the same security configuration options:

{
  "security": {
    "ssl_enabled": true,
    "ssl_cert_path": "/etc/ssl/cert.pem",
    "ssl_key_path": "/etc/ssl/key.pem",
    "domain": "api.example.com",
    
    "allowed_hosts": ["api.example.com", "app.example.com"],
    "cors_origins": ["https://app.example.com"],
    
    "max_request_size": 5242880,
    "rate_limit": 30,
    "request_timeout": 60,
    
    "use_hsts": true,
    "hsts_max_age": 31536000
  }
}

Migration guide

From environment variables only

Before:

export SWML_SSL_ENABLED=true
export SWML_SSL_CERT_PATH=/path/to/cert.pem
export SWML_BASIC_AUTH_USER=myuser

After:

{
  "security": {
    "ssl_enabled": "${SWML_SSL_ENABLED|false}",
    "ssl_cert_path": "${SWML_SSL_CERT_PATH}",
    "auth": {
      "basic": {
        "user": "${SWML_BASIC_AUTH_USER|signalwire}"
      }
    }
  }
}

Benefits of configuration files

• Environment isolation: Different configs for dev/staging/prod
• Documentation: Self-documenting configuration structure
• Validation: JSON schema validation available
• Reusability: Share configurations across deployments
• Security: Separate sensitive values using environment substitution

Configuration examples

Development setup

{
  "service": {
    "host": "localhost",
    "port": 3000
  },
  "security": {
    "ssl_enabled": false,
    "auth": {
      "basic": {
        "user": "dev",
        "password": "devpass123"
      }
    }
  }
}

Production setup

{
  "service": {
    "host": "${HOST|0.0.0.0}",
    "port": "${PORT|443}"
  },
  "security": {
    "ssl_enabled": true,
    "ssl_cert_path": "${SSL_CERT_PATH}",
    "ssl_key_path": "${SSL_KEY_PATH}",
    "domain": "${DOMAIN}",
    "auth": {
      "basic": {
        "user": "${AUTH_USER}",
        "password": "${AUTH_PASSWORD}"
      }
    },
    "allowed_hosts": ["${DOMAIN}"],
    "use_hsts": true
  }
}

Best practices

1. Use environment substitution for sensitive values
2. Validate configurations before deploying to production
3. Document custom configurations for your team
4. Test configurations in staging environments first
5. Version control non-sensitive configuration templates
6. Monitor configuration loading in application logs

For detailed security configuration options, see the Security guide.