> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# Environment Variables

> Complete reference for all environment variables used by the SignalWire Server SDK.

[ref-relayclient]: /docs/server-sdks/reference/typescript/relay/client

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.

> **Tip**
>
> Use `dotenv` to load variables from a `.env` file during development:
>
> ```typescript {1}
> import 'dotenv/config';
> import { AgentBase } from '@signalwire/sdk';
>
> const agent = new AgentBase({ name: 'my-agent' });
> ```

---

## Server

**`PORT`** `number` — default: 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.

---

> **Warning**
>
> 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`** `boolean` — default: 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`** `boolean` — default: false

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

---

**`SWML_TRUST_PROXY_HEADERS`** `boolean` — default: 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.

---

> **Warning**
>
> Setting `SWML_PROXY_URL_BASE` overrides SSL configuration and port settings
> for webhook URL generation.

---

## Schema Validation

**`SWML_SKIP_SCHEMA_VALIDATION`** `boolean` — default: 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`** `string` — default: \*

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

---

**`SWML_CSRF_PROTECTION`** `boolean` — default: 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`** `number` — default: 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`** `string` — default: auto

Logging mode.

* `"auto"` -- automatic detection based on environment
* `"off"` -- disable all logging
* `"stderr"` -- log to stderr

---

**`SIGNALWIRE_LOG_LEVEL`** `string` — default: 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`** `string` — default: 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`** `string` — default: 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`** `number` — default: 1000

Maximum concurrent calls per [`RelayClient`][ref-relayclient] instance.

---

**`RELAY_MAX_CONNECTIONS`** `number` — default: 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`** `string` — default: 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`** `string` — default: 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`** `string` — default: us-central1

Google Cloud region.

---

**`FUNCTION_TARGET`** `string` — default: unknown

Cloud Function entry point name.

---

**`K_SERVICE`** `string` — default: 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

```bash
# 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

```typescript {1}
import 'dotenv/config';
import { AgentBase } from '@signalwire/sdk';

const agent = new AgentBase({ name: 'my-agent' });

// Environment variables are now available to the SDK
```

> Complete reference for all environment variables used by the SignalWire Server SDK.