> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Configuration

> Environment variables, config files, and security settings.

[configloader]: /docs/server-sdks/reference/python/agents/configuration/config-loader

[environment-variables]: /docs/server-sdks/reference/python/agents/configuration/environment-variables

[authhandler]: /docs/server-sdks/reference/python/agents/configuration/auth-handler

[securityconfig]: /docs/server-sdks/reference/python/agents/configuration/security-config

[config-loader]: /docs/server-sdks/reference/python/agents/configuration/config-loader

[security-config]: /docs/server-sdks/reference/python/agents/configuration/security-config

[auth-handler]: /docs/server-sdks/reference/python/agents/configuration/auth-handler

The SignalWire Server SDK uses a layered configuration system. Settings can come
from constructor parameters, environment variables, JSON config files, or
sensible defaults. The layers are resolved in priority order:

1. **Constructor parameters** -- highest priority
2. **Config file values** -- loaded from JSON, override environment variables
3. **Environment variables** -- override defaults
4. **Defaults** -- built-in fallback values

```python
from signalwire import AgentBase

# Constructor parameters take precedence over everything else
agent = AgentBase(
    name="my-agent",
    port=9000,                        # Overrides PORT env var and config file
    config_file="my_config.json",     # Explicit config file path
)
```

## Config File Discovery

When no explicit `config_file` is provided, the SDK searches for JSON config
files in this order:

1. `config.json`
2. `agent_config.json`
3. `swml_config.json`
4. `.swml/config.json`
5. `~/.swml/config.json`
6. `/etc/swml/config.json`

See [`ConfigLoader`][configloader] for
the full file discovery logic and environment variable substitution syntax.

## Key Configuration Areas

| Area                     | Configured Via                                                      | Reference                                      |
| ------------------------ | ------------------------------------------------------------------- | ---------------------------------------------- |
| Server port, host, route | Constructor, `PORT` env var, config file                            | [Environment Variables][environment-variables] |
| Authentication           | `SWML_BASIC_AUTH_*` env vars, config file                           | [AuthHandler][authhandler]                     |
| SSL/HTTPS                | `SWML_SSL_*` env vars, config file                                  | [SecurityConfig][securityconfig]               |
| CORS and host allowlists | `SWML_CORS_ORIGINS`, `SWML_ALLOWED_HOSTS` env vars                  | [SecurityConfig][securityconfig]               |
| Logging                  | `SIGNALWIRE_LOG_MODE`, `SIGNALWIRE_LOG_LEVEL` env vars              | [Environment Variables][environment-variables] |
| Relay / REST auth        | `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_API_TOKEN`, `SIGNALWIRE_SPACE` | [Environment Variables][environment-variables] |

## Quick Example

```json
{
  "service": {
    "name": "support-agent",
    "host": "0.0.0.0",
    "port": 8080,
    "route": "/support"
  },
  "security": {
    "auth": {
      "basic": {
        "user": "${AUTH_USER|support_agent}",
        "password": "${AUTH_PASSWORD}"
      }
    },
    "ssl_enabled": true,
    "domain": "support.example.com",
    "ssl_cert_path": "/etc/ssl/certs/support.crt",
    "ssl_key_path": "/etc/ssl/private/support.key"
  },
  "agent": {
    "auto_answer": true,
    "record_call": false
  },
  "skills": [
    { "name": "datetime" },
    {
      "name": "native_vector_search",
      "params": {
        "index_file": "./support_docs.swsearch",
        "tool_name": "search_support"
      }
    }
  ]
}
```

#### [Environment Variables](/docs/server-sdks/reference/python/agents/configuration/environment-variables)

Complete reference for all environment variables used by the SDK.

#### [ConfigLoader](/docs/server-sdks/reference/python/agents/configuration/config-loader)

JSON config file loading with environment variable substitution.

#### [SecurityConfig](/docs/server-sdks/reference/python/agents/configuration/security-config)

SSL, CORS, host allowlists, rate limiting, and HSTS configuration.

#### [AuthHandler](/docs/server-sdks/reference/python/agents/configuration/auth-handler)

HTTP Basic Auth, Bearer tokens, and API key authentication for FastAPI and Flask.

> Environment variables, config files, and security settings.

## Docs

- [AuthHandler](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/auth-handler.md): Unified authentication handler for Basic Auth, Bearer tokens, and API keys.
- [flask_decorator](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/auth-handler/flask-decorator.md): Flask decorator for protecting routes with authentication.
- [get_auth_info](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/auth-handler/get-auth-info.md): Get a summary of configured authentication methods.
- [get_fastapi_dependency](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/auth-handler/get-fastapi-dependency.md): Get a FastAPI dependency function for protecting routes.
- [verify_api_key](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/auth-handler/verify-api-key.md): Verify an API key using constant-time comparison.
- [verify_basic_auth](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/auth-handler/verify-basic-auth.md): Verify HTTP Basic Auth credentials using constant-time comparison.
- [verify_bearer_token](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/auth-handler/verify-bearer-token.md): Verify a Bearer token using constant-time comparison.
- [ConfigLoader](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/config-loader.md): JSON configuration loading with environment variable substitution.
- [find_config_file](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/config-loader/find-config-file.md): Static method to locate a config file without loading it.
- [get](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/config-loader/get.md): Get a configuration value by dot-notation path.
- [get_config](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/config-loader/get-config.md): Get the raw configuration dictionary before environment variable substitution.
- [get_config_file](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/config-loader/get-config-file.md): Get the path of the loaded config file.
- [get_section](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/config-loader/get-section.md): Get an entire configuration section with environment variables substituted.
- [has_config](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/config-loader/has-config.md): Check whether a configuration file was successfully loaded.
- [merge_with_env](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/config-loader/merge-with-env.md): Merge configuration with environment variables matching a prefix.
- [substitute_vars](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/config-loader/substitute-vars.md): Recursively substitute environment variables in configuration values.
- [Environment Variables](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/environment-variables.md): Complete reference for all environment variables used by the SignalWire Server SDK.
- [SecurityConfig](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/security-config.md): Unified security configuration for SSL, CORS, host allowlists, and rate limiting.
- [get_basic_auth](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/security-config/get-basic-auth.md): Get basic authentication credentials, generating a password if not set.
- [get_cors_config](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/security-config/get-cors-config.md): Get CORS configuration suitable for FastAPI's CORSMiddleware.
- [get_security_headers](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/security-config/get-security-headers.md): Get security headers to add to HTTP responses.
- [get_ssl_context_kwargs](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/security-config/get-ssl-context-kwargs.md): Get SSL parameters suitable for passing to uvicorn.
- [get_url_scheme](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/security-config/get-url-scheme.md): Get the URL scheme based on SSL configuration.
- [load_from_env](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/security-config/load-from-env.md): Reload all settings from environment variables.
- [log_config](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/security-config/log-config.md): Log the current security configuration for debugging.
- [should_allow_host](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/security-config/should-allow-host.md): Check if a host is in the allowed hosts list.
- [validate_ssl_config](https://signalwire.com/docs/server-sdks/reference/python/agents/configuration/security-config/validate-ssl-config.md): Validate that SSL configuration is complete and certificate files exist.