Environment Variables

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

Username for HTTP Basic Authentication on all agent webhook endpoints. When a password is set without a user, the user is signalwire. When the password is generated, the user falls back to the agent’s name.

Password for HTTP Basic Authentication. Credentials resolve from the constructor’s basicAuth, then the config file, then these variables. If none is set, a random password is generated on each startup; it exists only in that process, and the agent logs a warning.

Secret that signs per-call SWAIG function tokens, used when the agent’s swaigSecret option isn’t set. Set the same value on every replica, and keep it across restarts, so a token issued by one process validates on another. Treat it as a secret.

Enable HTTPS for serve() and AgentServer.run(). Accepts true, 1, or yes. Webhook URLs then use https, on SWML_SSL_DOMAIN when it’s set. When the certificate or key file is missing, the agent warns and serves HTTP.

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

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

Domain name for HSTS headers and URL generation.

Build webhook URLs with https even when the agent itself serves HTTP, as it does behind a proxy that terminates TLS. Only the string "true" is accepted.

Send a Strict-Transport-Security header on HTTPS responses. Once the variable is set, any value other than "true" turns the header off.

max-age, in seconds, of the Strict-Transport-Security header. A value that isn’t a number is ignored.

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.

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

The SDK’s outbound URL fetches (the spider and web_search skills, for example) connect directly, ignoring any environment proxy, so each connection can be checked for private and internal addresses. When set, a request that Node’s global fetch would send through a proxy goes through it instead, where that check can’t apply. Use a proxy that restricts destinations itself. Accepts 1, true, or yes.

Let the SDK’s outbound URL fetches reach private and internal addresses, which they otherwise refuse. Accepts 1, true, or yes. Set it only when a skill must reach a host on your own network.

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

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.

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.

Comma-separated list of allowed Host header values. When unset, or when the list includes *, 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").

Comma-separated list of allowed CORS origins. A list that includes * allows every origin. Restrict to trusted origins in production.

When set to "true", POST requests whose Origin header is not in SWML_CORS_ORIGINS are rejected with HTTP 403. A request with no Origin header passes, and nothing is rejected while SWML_CORS_ORIGINS includes *. Only the string "true" is accepted.

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

Rate limit in requests per minute per client. When unset, no rate limit is applied. When set to a positive integer, clients exceeding the limit receive HTTP 429. Each client is keyed by its connection address, by the forwarded address when SWML_TRUST_PROXY_HEADERS is set, or on a serverless platform by the address the platform reports.

Logging mode.

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

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

Log output format.

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

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

Publishable key a ChatGateway accepts from the browser widget, used when the gateway’s key option isn’t set. Without either, the gateway generates a key, which is only useful to a process that also serves the page.

Key that signs a ChatGateway’s conversation handles, used when the gateway’s secret option isn’t set. Without either, each process generates its own, and outstanding handles stop working on restart and across replicas. Treat it as a secret.

Colon-separated paths to directories containing custom skills. The skill registry scans these paths in addition to the built-in skills directory, but only when SWML_SKILL_DISCOVERY_ENABLED is "true".

Allow the skill registry to import skills from directories, through discoverFromDirectory() and the paths in SIGNALWIRE_SKILL_PATHS. Without it, discovery logs a warning and registers nothing. Only the string "true" is accepted.

Allow the custom_skills skill to compile and run handler code from its configuration. Without it, those tools return an error instead of running. Only the string "true" is accepted.

SignalWire project ID for authentication.

API token for authentication.

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

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 and accepts either the hostname or the bare space name, your-space, to which it appends .signalwire.com.

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.

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

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

WebSocket scheme for the Relay connection, wss or ws.

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

Maximum concurrent calls per RelayClient instance.

Maximum concurrent RelayClient connections per process.

Lambda function name. Used for URL construction and logging.

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

AWS region for Lambda execution.

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

Lambda environment detection variable, read alongside AWS_LAMBDA_FUNCTION_NAME. Set automatically by the Lambda runtime.

The function’s URL. When set, webhook URLs use it. Otherwise they are built as https://<region>-<project>.cloudfunctions.net/<service> from the variables below.

Cloud Function entry point name, set by the Functions Framework. Without it and without FUNCTION_URL, the agent builds no Cloud Function URL. Cloud Run sets K_SERVICE without FUNCTION_TARGET, so a server there isn’t taken for a Cloud Function.

Google Cloud project ID used in the built URL. GCP_PROJECT is read when it’s unset. With neither, webhook URLs use https://localhost:8080.

Fallback for GOOGLE_CLOUD_PROJECT.

Google Cloud region used in the built URL. GOOGLE_CLOUD_REGION is read when it’s unset.

Fallback for FUNCTION_REGION.

Service name used in the built URL. Falls back to FUNCTION_TARGET.

Project ID read only by ServerlessAdapter’s generateUrl(). The agent’s own webhook URLs use GOOGLE_CLOUD_PROJECT.

Azure Functions environment detection variable.

Azure Functions environment name.

The function’s URL. When set, webhook URLs use it.

Function app name. With AZURE_FUNCTION_NAME, builds the webhook URL https://<app>.azurewebsites.net/api/<function> when AZURE_FUNCTION_URL isn’t set. AZURE_FUNCTIONS_APP_NAME is read when it’s unset.

Fallback for WEBSITE_SITE_NAME.

Function name used in the built webhook URL.

CGI environment detection variable.