Environment Variables

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

import 'dotenv/config';
import { AgentBase } from '@signalwire/sdk';
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.

Webhook signature validation

SIGNALWIRE_SIGNING_KEY

string

Your SignalWire Signing Key. When set (or when the signingKey constructor option is passed), the agent validates the signature on every inbound webhook and rejects unsigned or mis-signed requests with HTTP 403. Treat it as a secret.

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. Case-insensitive; an unrecognized value falls back to "info".

"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

SIGNALWIRE_LOG_COLOR

boolean

Force colored text output on ("true") or off ("false"). When unset, color is enabled only when writing to a terminal.

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

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

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

string

Your space hostname, for example your-space.signalwire.com. RestClient uses it as the REST API host and throws when neither this variable, the host option, nor SIGNALWIRE_REST_BASE_URL 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, set SIGNALWIRE_RELAY_HOST=relay.signalwire.com or pass host to RelayClient so the REST setting does not redirect the WebSocket connection.

SIGNALWIRE_REST_BASE_URL

string

Full base URL for REST requests (e.g., https://your-space.signalwire.com). Takes precedence over SIGNALWIRE_SPACE; the host constructor option takes precedence over both.

SIGNALWIRE_REST_CA_FILE

string

Path to a PEM file of additional CA certificates trusted for REST connections. Adds trust; it never disables certificate verification.

SIGNALWIRE_RELAY_HOST

string

Override the Relay WebSocket host. Takes precedence over SIGNALWIRE_SPACE; the host constructor option takes precedence over both.

SIGNALWIRE_RELAY_SCHEME

stringDefaults to wss

WebSocket scheme for the Relay connection, wss or ws.

SIGNALWIRE_RELAY_CA_FILE

string

Path to a PEM file of additional CA certificates trusted for the Relay WebSocket connection. Adds trust; it never disables certificate verification.

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
# REST host. RelayClient reads it too; set SIGNALWIRE_RELAY_HOST to keep the default.
SIGNALWIRE_SPACE=your-space.signalwire.com
# Custom Skills
SIGNALWIRE_SKILL_PATHS=/opt/custom_skills

Loading .env in TypeScript

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