AgentsConfiguration

Environment Variables

View as MarkdownOpen in Claude

The SignalWire Server 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:

from dotenv import load_dotenv
load_dotenv()
from signalwire import AgentBase
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.

SIGNALWIRE_SIGNING_KEY
str

Your SignalWire Signing Key. When set, the agent validates the signature on POST /, /swaig, and /post_prompt requests and rejects unsigned or invalidly signed requests with 403. The signing_key constructor argument takes precedence.

SIGNALWIRE_SWAIG_SECRET
str

Secret used to sign the agent’s per-call SWAIG function tokens. When unset, a random secret is generated per process, so tokens stop verifying after a restart or when a tool call lands on a different replica. Set it in production. The swaig_secret constructor argument takes precedence.

SWML_TRUST_REMOTE_USER
boolDefaults to false

In CGI mode, accept a request authenticated by the web server (REMOTE_USER) when no HTTP_AUTHORIZATION header is present. Accepts "1", "true", or "yes".

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.

SWML_TRUST_PROXY_HEADERS
boolDefaults to false

Trust X-Forwarded-Host and X-Forwarded-Proto headers when detecting the public URL for webhook generation. Accepts 1, true, or yes. Enable only behind a reverse proxy you control. Setting SWML_PROXY_URL_BASE implies it.

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.

SWML_ALLOW_PRIVATE_URLS
boolDefaults to false

Let URL validation accept hosts that resolve to private, loopback, or link-local addresses. Accepts "1", "true", or "yes". Leave unset in production; it disables the SDK’s protection against server-side request forgery.

AI chat gateway

SIGNALWIRE_CHAT_GATEWAY_KEY
str

Publishable key a ChatGateway accepts from the browser when no key is passed to its constructor. A random pk_ value is generated if neither is set.

SIGNALWIRE_CHAT_GATEWAY_SECRET
str

HMAC secret a ChatGateway uses to sign handles when no secret is passed. A random per-process value is generated if neither is set, which invalidates outstanding handles on restart.

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

RelayClient, RestClient, and AIChatClient read these variables. The three clients agree on the credential variables but not on SIGNALWIRE_SPACE, so read that entry before setting it in a process that uses more than one 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.

The SDK reads SIGNALWIRE_API_TOKEN only. Older examples that used SIGNALWIRE_TOKEN need to be updated; that name is not read anywhere.

SIGNALWIRE_SPACE
str

Your space hostname, for example your-space.signalwire.com. RestClient uses it as the REST API host and raises ValueError when neither this variable nor the host argument is set. AIChatClient reads the same variable but expects the bare space name, your-space, and appends .signalwire.com itself.

Relay reads SIGNALWIRE_SPACE too

RelayClient connects to relay.signalwire.com by default and needs no space setting. When SIGNALWIRE_SPACE is set, it connects to that host instead. If the same process uses REST and Relay, pass host="relay.signalwire.com" to RelayClient so the REST setting does not redirect the WebSocket connection.

sw-agent-init and sw-agent-dokku read and write a different variable, SIGNALWIRE_SPACE_NAME, holding the bare space name. No client reads it, so a scaffolded project still needs SIGNALWIRE_SPACE before RestClient() can start from the environment.

SIGNALWIRE_REST_CA_FILE
str

Path to a CA bundle the REST client trusts for TLS verification. Unset uses the default trust store.

SIGNALWIRE_RELAY_CA_FILE
str

Path to a CA bundle the Relay WebSocket client trusts for TLS verification. Unset uses the system trust store.

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.

PATH_INFO
str

Request path following the script name. Used to route the request to the matching agent.

CONTENT_LENGTH
str

Size of the POST body in bytes, read from stdin for SWAIG function calls.

Example .env File

# Server
PORT=3000
# Authentication
SWML_BASIC_AUTH_USER=agent_user
SWML_BASIC_AUTH_PASSWORD=secret_password_123
SIGNALWIRE_SIGNING_KEY=your-signing-key
SIGNALWIRE_SWAIG_SECRET=a-stable-secret-across-replicas
# 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
# REST host. RelayClient reads it too; pass host="relay.signalwire.com" there.
SIGNALWIRE_SPACE=your-space.signalwire.com
# Custom Skills
SIGNALWIRE_SKILL_PATHS=/opt/custom_skills

Loading .env in Python

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