AgentsConfiguration

Environment Variables

View as MarkdownOpen in Claude

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:

1from dotenv import load_dotenv
2load_dotenv()
3
4from signalwire import AgentBase
5agent = 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

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