Config files

Config files enable granular, isolated control of development, staging, and production environments, and allow substitution of sensitive values using environment variables.

Usage

Auto-load

The simplest way to start is to place a config.json file next to your agent in the project directory. It will be loaded automatically.

.
├── config.json
├── dev-agent.py
└── venv

Declare path

If you want to specify the path to your config file, pass it in using the config_file parameter.

With AgentBase class
With a custom class

agent.py
from signalwire_agents import AgentBase

# Create an agent
agent = AgentBase(name="Sigmond", config_file="./path/to/config.json")

# Start the agent
agent.serve()

When using a custom class, make sure to include the **kwargs parameter in the two places shown below.

This allows our custom TestAgent class to accept and pass through any AgentBase parameters (like config_file) without explicitly defining each one in the constructor.

agent.py
from signalwire_agents import AgentBase

class TestAgent(AgentBase):

    def __init__(self, **kwargs):
        super().__init__(name="test", **kwargs)

agent = TestAgent(config_file="./path/to/config.json")

# Start the agent
agent.serve()

Structure

Configuration files use JSON format with environment variable substitution. Here's a complete example showing the main configuration sections:

{
  "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}"
  }
}

Service options

Option	Type	Default	Description
`service.name`	string	-	Service name for identification. This is the name set when instantiating your agent.
`service.host`	string	`"0.0.0.0"`	Host/IP address to bind to
`service.port`	number	`3000`	Port number to listen on
`service.route`	string	`"/"`	Base route path for the service

Security options

All services share the same security configuration options:

Option	Type	Default	Description
`ssl_enabled`	boolean	`false`	Enable HTTPS/SSL encryption
`ssl_cert_path`	string	-	Path to SSL certificate file
`ssl_key_path`	string	-	Path to SSL private key file
`domain`	string	-	Domain name for SSL configuration
`allowed_hosts`	array	`["*"]`	List of allowed host headers
`cors_origins`	array	`["*"]`	List of allowed CORS origins
`max_request_size`	number	`10485760`	Maximum request size in bytes (10MB)
`rate_limit`	number	`60`	Requests per minute
`request_timeout`	number	`30`	Request timeout in seconds
`use_hsts`	boolean	`true`	Enable HTTP Strict Transport Security
`hsts_max_age`	number	`31536000`	HSTS max age in seconds (1 year)

Here's a comprehensive example:

{
  "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
  }
}

Prioritization

Services in the Agents SDK look for configuration files in the below locations, in this order:

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

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

Constructor parameters - Explicitly passed to service
Config file values - From JSON configuration
Environment variables - Direct env vars
Defaults - Hard-coded defaults

Environment variables

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

For example:

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

Set environment variables

Best practices and recommendations for working with environment variables in your application

Environment variables can be set in several ways depending on your deployment method. For example:

.env file
Command line
Docker
Docker Compose
Kubernetes

Create a .env file in your project root (add to .gitignore):

.env
DB_PASSWORD=mysecretpassword
SSL_ENABLED=true
AUTH_USER=myuser

Optionally, use python-dotenv to load the .env variables:

pip install python-dotenv

from dotenv import load_dotenv
load_dotenv()  # This loads the .env file

Run the following commands in sequence:

export DB_PASSWORD=mysecretpassword
export SSL_ENABLED=true
export AUTH_USER=myuser

docker run -e DB_PASSWORD=mysecretpassword -e SSL_ENABLED=true myapp

environment:
  - DB_PASSWORD=mysecretpassword
  - SSL_ENABLED=true
  - AUTH_USER=myuser

env:
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: db-secret
        key: password

For serverless deployment, refer to each provider's docs on managing environment variables:

AWS Lambda

Configure environment variables for Lambda functions

Google Cloud Functions

Set environment variables in Cloud Functions

Azure Functions

Manage app settings and environment variables

Examples

Development

This simple config sets up basic auth without SSL on port 3000.

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

Production

This config secures your service with SSL encryption, domain-based host restrictions, and environment variable substitution for sensitive credentials.

{
  "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

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

For detailed security configuration options, see the Security guide.

Usage​

Auto-load​

Declare path​

Structure​

Service options​

Security options​

Prioritization​

Environment variables​

Substitution​