Environment Variables

The SignalWire Agents SDK reads environment variables for server configuration, authentication, SSL, logging, RELAY/REST client credentials, and serverless platform detection. Environment variables are overridden by constructor parameters but take precedence over config file values.

Use python-dotenv to load variables from a .env file during development:

1 from dotenv import load_dotenv
2 load_dotenv()
3 
4 from signalwire import AgentBase
5 agent = AgentBase(name="my-agent")

Server

PORT

intDefaults to 3000

Server port. Used when no port argument is passed to the constructor.

Authentication

SWML_BASIC_AUTH_USER

str

Username for HTTP Basic Authentication on all agent webhook endpoints. If not set, get_basic_auth() defaults the username to "signalwire".

SWML_BASIC_AUTH_PASSWORD

str

Password for HTTP Basic Authentication. If not set, a random password is auto-generated on each startup and printed to the console.

In production, always set SWML_BASIC_AUTH_PASSWORD explicitly. Auto-generated passwords change on every restart, which will break SignalWire webhook callbacks until you update the credentials in your SignalWire dashboard.

SSL / TLS

SWML_SSL_ENABLED

boolDefaults to false

Enable HTTPS. Accepts "true", "1", or "yes".

SWML_SSL_CERT_PATH

str

Path to the SSL certificate file (.pem or .crt). Required when SWML_SSL_ENABLED is set.

SWML_SSL_KEY_PATH

str

Path to the SSL private key file (.key). Required when SWML_SSL_ENABLED is set.

SWML_DOMAIN

str

Domain name for SSL certificates and URL generation.

SWML_SSL_VERIFY_MODE

strDefaults to CERT_REQUIRED

SSL certificate verification mode.

Proxy

SWML_PROXY_URL_BASE

str

Base URL when running behind a reverse proxy (e.g., https://my-agent.example.com). The agent uses this URL to generate correct webhook URLs in SWML documents.

APP_URL

str

Fallback for SWML_PROXY_URL_BASE when that variable is not set.

SWML_PROXY_DEBUG

boolDefaults to false

Enable proxy request debug logging.

Setting SWML_PROXY_URL_BASE (or APP_URL) overrides SSL configuration and port settings for webhook URL generation.

Schema Validation

SWML_SKIP_SCHEMA_VALIDATION

boolDefaults to false

Disable SWML document schema validation. Accepts "1", "true", or "yes". Useful for performance in production when you trust your SWML output.

Security

SWML_ALLOWED_HOSTS

strDefaults to *

Comma-separated list of allowed hosts. Set to specific domain(s) in production (e.g., "agent.example.com,api.example.com").

SWML_CORS_ORIGINS

strDefaults to *

Comma-separated list of allowed CORS origins. Restrict to trusted origins in production.

SWML_MAX_REQUEST_SIZE

intDefaults to 10485760

Maximum request body size in bytes. Default is 10 MB.

SWML_RATE_LIMIT

intDefaults to 60

Rate limit in requests per minute.

SWML_REQUEST_TIMEOUT

intDefaults to 30

Request timeout in seconds.

SWML_USE_HSTS

boolDefaults to true

Enable HTTP Strict Transport Security headers when serving over HTTPS.

SWML_HSTS_MAX_AGE

intDefaults to 31536000

HSTS max-age directive in seconds. Default is 1 year.

Logging

SIGNALWIRE_LOG_MODE

strDefaults to auto

Logging mode.

"auto" — automatic detection based on environment
"off" — disable all logging
"stderr" — log to stderr
"default" — standard logging output

SIGNALWIRE_LOG_LEVEL

strDefaults to info

Log level.

"debug" — verbose output for development and troubleshooting
"info" — standard operational messages
"warning" — potential issues that do not prevent operation
"error" — failures that affect a specific operation
"critical" — severe failures that may prevent the service from running

SIGNALWIRE_LOG_FORMAT

strDefaults to console

Log output format.

"console" — colored human-readable output (default)
"json" — structured JSON log lines for log aggregation systems

Skills

SIGNALWIRE_SKILL_PATHS

str

Colon-separated paths to directories containing custom skills. The skill registry scans these paths in addition to the built-in skills directory.

RELAY and REST Client

These variables are shared between the RELAY WebSocket client and the REST HTTP client.

SIGNALWIRE_PROJECT_ID

str

SignalWire project ID for authentication.

SIGNALWIRE_API_TOKEN

str

API token for authentication.

SIGNALWIRE_JWT_TOKEN

str

JWT token for RELAY authentication. Alternative to project ID + API token.

SIGNALWIRE_SPACE

strDefaults to relay.signalwire.com

Space hostname used for RELAY WebSocket connections and as the REST API base URL.

RELAY_MAX_ACTIVE_CALLS

intDefaults to 1000

Maximum concurrent calls per RelayClient instance.

RELAY_MAX_CONNECTIONS

intDefaults to 1

Maximum concurrent RelayClient connections per process.

Serverless Platforms

The SDK auto-detects the execution environment from platform-specific variables. You typically do not set these manually — they are provided by the platform runtime.

AWS Lambda

AWS_LAMBDA_FUNCTION_NAME

strDefaults to unknown

Lambda function name. Used for URL construction and logging.

AWS_LAMBDA_FUNCTION_URL

str

Lambda function URL. If not set, constructed from region and function name.

AWS_REGION

strDefaults to us-east-1

AWS region for Lambda execution.

LAMBDA_TASK_ROOT

str

Lambda environment detection variable. Set automatically by the Lambda runtime.

Google Cloud Functions

GOOGLE_CLOUD_PROJECT

str

Google Cloud project ID.

GCP_PROJECT

str

Alternative to GOOGLE_CLOUD_PROJECT.

GOOGLE_CLOUD_REGION

strDefaults to us-central1

Google Cloud region.

FUNCTION_TARGET

strDefaults to unknown

Cloud Function entry point name.

K_SERVICE

strDefaults to unknown

Knative/Cloud Run service name.

Azure Functions

AZURE_FUNCTIONS_ENVIRONMENT

str

Azure Functions environment detection variable.

WEBSITE_SITE_NAME

str

Azure App Service site name. Used to construct function URLs.

AZURE_FUNCTION_NAME

strDefaults to unknown

Azure Function name.

CGI

GATEWAY_INTERFACE

str

CGI environment detection variable.

HTTP_HOST

str

HTTP Host header value. Falls back to SERVER_NAME.

SERVER_NAME

strDefaults to localhost

Server hostname.

SCRIPT_NAME

str

CGI script path.

Example .env File

$ # Server
$ PORT=3000
$ 
$ # Authentication
$ SWML_BASIC_AUTH_USER=agent_user
$ SWML_BASIC_AUTH_PASSWORD=secret_password_123
$ 
$ # SSL Configuration
$ SWML_SSL_ENABLED=true
$ SWML_DOMAIN=agent.example.com
$ SWML_SSL_CERT_PATH=/etc/ssl/certs/agent.crt
$ SWML_SSL_KEY_PATH=/etc/ssl/private/agent.key
$ 
$ # Security
$ SWML_ALLOWED_HOSTS=agent.example.com
$ SWML_CORS_ORIGINS=https://app.example.com
$ SWML_RATE_LIMIT=100
$ 
$ # Logging
$ SIGNALWIRE_LOG_MODE=default
$ SIGNALWIRE_LOG_LEVEL=info
$ 
$ # RELAY / REST
$ SIGNALWIRE_PROJECT_ID=your-project-id
$ SIGNALWIRE_API_TOKEN=your-api-token
$ SIGNALWIRE_SPACE=your-space.signalwire.com
$ 
$ # Custom Skills
$ SIGNALWIRE_SKILL_PATHS=/opt/custom_skills

Loading .env in Python

1 from dotenv import load_dotenv
2 load_dotenv()
3 
4 from signalwire import AgentBase
5 agent = AgentBase(name="my-agent")
6 
7 # Environment variables are now available to the SDK
8 username, password, source = agent.get_basic_auth_credentials(include_source=True)
9 print(f"Auth: {username}:{password} (source: {source})")

1	from dotenv import load_dotenv
2	load_dotenv()
3
4	from signalwire import AgentBase
5	agent = AgentBase(name="my-agent")

$	# Server
$	PORT=3000
$
$	# Authentication
$	SWML_BASIC_AUTH_USER=agent_user
$	SWML_BASIC_AUTH_PASSWORD=secret_password_123
$
$	# SSL Configuration
$	SWML_SSL_ENABLED=true
$	SWML_DOMAIN=agent.example.com
$	SWML_SSL_CERT_PATH=/etc/ssl/certs/agent.crt
$	SWML_SSL_KEY_PATH=/etc/ssl/private/agent.key
$
$	# Security
$	SWML_ALLOWED_HOSTS=agent.example.com
$	SWML_CORS_ORIGINS=https://app.example.com
$	SWML_RATE_LIMIT=100
$
$	# Logging
$	SIGNALWIRE_LOG_MODE=default
$	SIGNALWIRE_LOG_LEVEL=info
$
$	# RELAY / REST
$	SIGNALWIRE_PROJECT_ID=your-project-id
$	SIGNALWIRE_API_TOKEN=your-api-token
$	SIGNALWIRE_SPACE=your-space.signalwire.com
$
$	# Custom Skills
$	SIGNALWIRE_SKILL_PATHS=/opt/custom_skills