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 dotenv to load variables from a .env file during development:

1 import 'dotenv/config';
2 import { AgentBase } from '@signalwire/sdk';
3 
4 const agent = new AgentBase({ name: 'my-agent' });

Server

PORT

numberDefaults to 3000

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

Authentication

SWML_BASIC_AUTH_USER

string

Username for HTTP Basic Authentication on all agent webhook endpoints. When unset, the username falls back to the agent’s name.

SWML_BASIC_AUTH_PASSWORD

string

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

booleanDefaults to false

Enable HTTPS. Only the string "true" is accepted (strict equality check).

SWML_SSL_CERT_PATH

string

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

SWML_SSL_KEY_PATH

string

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

SWML_SSL_DOMAIN

string

Domain name for HSTS headers and URL generation.

Proxy

SWML_PROXY_URL_BASE

string

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.

SWML_PROXY_DEBUG

booleanDefaults to false

Enable proxy request debug logging. Only the string "true" is accepted.

SWML_TRUST_PROXY_HEADERS

booleanDefaults to false

Trust X-Forwarded-For, X-Forwarded-Proto, and X-Forwarded-Host headers for client IP detection (used by rate limiting) and auto-detection of the public URL. Only the string "true" is accepted. Enable only when running behind a reverse proxy you control.

Setting SWML_PROXY_URL_BASE overrides SSL configuration and port settings for webhook URL generation.

Schema Validation

SWML_SKIP_SCHEMA_VALIDATION

booleanDefaults to false

Disable SWML document schema validation. Only the string "true" is accepted (strict equality check). Useful for performance in production when you trust your SWML output.

Security

SWML_ALLOWED_HOSTS

string

Comma-separated list of allowed Host header values. When unset, no host check is applied. When set, requests with a Host header not in the list are rejected with HTTP 403. Set to specific domain(s) in production (e.g., "agent.example.com,api.example.com").

SWML_CORS_ORIGINS

stringDefaults to *

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

SWML_CSRF_PROTECTION

booleanDefaults to false

When set to "true", POST requests whose Origin header is not in SWML_CORS_ORIGINS are rejected with HTTP 403. Only the string "true" is accepted.

SWML_MAX_REQUEST_SIZE

numberDefaults to 1048576

Maximum request body size in bytes. Default is 1 MB. Requests exceeding this size are rejected with HTTP 413.

SWML_RATE_LIMIT

number

Rate limit in requests per minute per client IP. When unset, no rate limit is applied. When set to a positive integer, clients exceeding the limit receive HTTP 429.

Logging

SIGNALWIRE_LOG_MODE

stringDefaults to auto

Logging mode.

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

SIGNALWIRE_LOG_LEVEL

stringDefaults to info

Log level.

"debug" — verbose output for development and troubleshooting
"info" — standard operational messages
"warn" — potential issues that do not prevent operation
"error" — failures that affect a specific operation

SIGNALWIRE_LOG_FORMAT

stringDefaults to text

Log output format.

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

Skills

SIGNALWIRE_SKILL_PATHS

string

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

string

SignalWire project ID for authentication.

SIGNALWIRE_API_TOKEN

string

API token for authentication.

SIGNALWIRE_JWT_TOKEN

string

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

SIGNALWIRE_SPACE

stringDefaults to relay.signalwire.com

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

RELAY_MAX_ACTIVE_CALLS

numberDefaults to 1000

Maximum concurrent calls per RelayClient instance.

RELAY_MAX_CONNECTIONS

numberDefaults 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

stringDefaults to unknown

Lambda function name. Used for URL construction and logging.

AWS_LAMBDA_FUNCTION_URL

string

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

AWS_REGION

stringDefaults to us-east-1

AWS region for Lambda execution.

_HANDLER

string

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

Google Cloud Functions

GCLOUD_PROJECT

string

Google Cloud project ID.

FUNCTION_REGION

stringDefaults to us-central1

Google Cloud region.

FUNCTION_TARGET

stringDefaults to unknown

Cloud Function entry point name.

K_SERVICE

stringDefaults to unknown

Knative/Cloud Run service name.

Azure Functions

FUNCTIONS_WORKER_RUNTIME

string

Azure Functions environment detection variable.

AZURE_FUNCTIONS_ENVIRONMENT

string

Azure Functions environment name.

CGI

GATEWAY_INTERFACE

string

CGI environment detection variable.

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_SSL_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=auto
$ 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 TypeScript

1 import 'dotenv/config';
2 import { AgentBase } from '@signalwire/sdk';
3 
4 const agent = new AgentBase({ name: 'my-agent' });
5 
6 // Environment variables are now available to the SDK

1	import 'dotenv/config';
2	import { AgentBase } from '@signalwire/sdk';
3
4	const agent = new 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_SSL_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=auto
$	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