> 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.

# Configuration

> Environment variables, config files, and security settings.

[configloader]: /docs/server-sdks/reference/typescript/agents/configuration/config-loader

[environment-variables]: /docs/server-sdks/reference/typescript/agents/configuration/environment-variables

[authhandler]: /docs/server-sdks/reference/typescript/agents/configuration/auth-handler

[promptmanager]: /docs/server-sdks/reference/typescript/agents/configuration/prompt-manager

[schemautils]: /docs/server-sdks/reference/typescript/agents/configuration/schema-utils

[serverlessadapter]: /docs/server-sdks/reference/typescript/agents/configuration/serverless-adapter

[sessionmanager]: /docs/server-sdks/reference/typescript/agents/configuration/session-manager

The SignalWire Server SDK uses a layered configuration system. Settings can come
from constructor parameters, environment variables, JSON config files, or
sensible defaults. The layers are resolved in priority order:

1. **Constructor parameters** -- highest priority
2. **Environment variables** -- override config file values
3. **Config file values** -- loaded from JSON
4. **Defaults** -- built-in fallback values

```typescript {4}
import { ConfigLoader } from '@signalwire/sdk';

// Constructor parameters take precedence over everything else
const config = new ConfigLoader('./my_config.json');
const port = config.get<number>('server.port', 3000);
```

## Config File Discovery

When no explicit config file path is provided, the SDK searches for JSON config
files using `ConfigLoader.search()`, which checks these locations in order:

1. Current working directory
2. `./config/`
3. `~/.signalwire/`

See [`ConfigLoader`][configloader] for
the full file discovery logic and environment variable substitution syntax.

## Key Configuration Areas

| Area                     | Configured Via                                                      | Reference                                      |
| ------------------------ | ------------------------------------------------------------------- | ---------------------------------------------- |
| Server port, host, route | Constructor, `PORT` env var, config file                            | [Environment Variables][environment-variables] |
| Authentication           | `SWML_BASIC_AUTH_*` env vars, config file                           | [AuthHandler][authhandler]                     |
| CORS and host allowlists | `SWML_CORS_ORIGINS`, `SWML_ALLOWED_HOSTS` env vars                  | [Environment Variables][environment-variables] |
| Logging                  | `SIGNALWIRE_LOG_MODE`, `SIGNALWIRE_LOG_LEVEL` env vars              | [Environment Variables][environment-variables] |
| Relay / REST auth        | `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_API_TOKEN`, `SIGNALWIRE_SPACE` | [Environment Variables][environment-variables] |

## Quick Example

```json
{
  "service": {
    "name": "support-agent",
    "host": "0.0.0.0",
    "port": 8080,
    "route": "/support"
  },
  "security": {
    "basic_auth": {
      "username": "${AUTH_USER|support_agent}",
      "password": "${AUTH_PASSWORD}"
    }
  },
  "agent": {
    "auto_answer": true,
    "record_call": false
  },
  "skills": [
    { "name": "datetime" },
    {
      "name": "native_vector_search",
      "params": {
        "index_file": "./support_docs.swsearch",
        "tool_name": "search_support"
      }
    }
  ]
}
```

#### [Environment Variables](/docs/server-sdks/reference/typescript/agents/configuration/environment-variables)

Complete reference for all environment variables used by the SDK.

#### [ConfigLoader](/docs/server-sdks/reference/typescript/agents/configuration/config-loader)

JSON config file loading with environment variable substitution.

#### [AuthHandler](/docs/server-sdks/reference/typescript/agents/configuration/auth-handler)

HTTP Basic Auth, Bearer tokens, and API key authentication for Hono middleware.

#### [PromptManager](/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager)

Manages agent prompt text with raw text and structured POM-based prompts.

#### [SchemaUtils](/docs/server-sdks/reference/typescript/agents/configuration/schema-utils)

SWML document validation against structural rules with result caching.

#### [ServerlessAdapter](/docs/server-sdks/reference/typescript/agents/configuration/serverless-adapter)

Adapts Hono apps for AWS Lambda, Google Cloud Functions, and Azure Functions.

#### [SessionManager](/docs/server-sdks/reference/typescript/agents/configuration/session-manager)

Stateless HMAC-SHA256 token generation and validation for SWAIG function calls.

#### [SslConfig](/docs/server-sdks/reference/typescript/agents/configuration/ssl-config)

SSL/TLS configuration for HTTPS serving with HSTS support.

#### [Logging](/docs/server-sdks/reference/typescript/agents/configuration/logging)

Structured logging with Logger class and global configuration functions.

> Environment variables, config files, and security settings.

## Docs

- [AuthHandler](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/auth-handler.md): Multi-method authentication handler with timing-safe credential comparison.
- [expressMiddleware](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/auth-handler/express-middleware.md): Create an Express/Connect-compatible middleware adapter.
- [getAuthInfo](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/auth-handler/get-auth-info.md): Get structured metadata describing the enabled authentication methods.
- [hasApiKeyAuth](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/auth-handler/has-api-key-auth.md): Check whether API key authentication is configured.
- [hasBasicAuth](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/auth-handler/has-basic-auth.md): Check whether Basic authentication is configured.
- [hasBearerAuth](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/auth-handler/has-bearer-auth.md): Check whether Bearer token authentication is configured.
- [middleware](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/auth-handler/middleware.md): Create a Hono-compatible middleware that rejects unauthorized requests.
- [validate](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/auth-handler/validate.md): Validate request headers against all configured authentication methods.
- [verifyApiKey](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/auth-handler/verify-api-key.md): Verify an API key against the configured key.
- [verifyBasicAuth](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/auth-handler/verify-basic-auth.md): Verify a username/password pair against the configured Basic Auth credentials.
- [verifyBearerToken](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/auth-handler/verify-bearer-token.md): Verify a Bearer token against the configured token.
- [ConfigLoader](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader.md): JSON configuration file loader with environment variable interpolation and dot-notation access.
- [findConfigFile](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/find-config-file.md): Find a config file path without loading it (static helper).
- [get](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/get.md): Retrieve a configuration value using a dot-notation path.
- [getAll](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/get-all.md): Return a shallow copy of the entire configuration object.
- [getConfig](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/get-config.md): Return a shallow copy of the entire configuration (Python-compat alias for getAll).
- [getConfigFile](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/get-config-file.md): Return the path of the loaded config file (Python-compat alias for getFilePath).
- [getFilePath](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/get-file-path.md): Return the absolute path of the loaded config file.
- [getSection](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/get-section.md): Get a configuration section with environment variables substituted.
- [has](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/has.md): Check whether a dot-notation path exists in the loaded configuration.
- [hasConfig](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/has-config.md): Check whether any configuration data is loaded (file or object).
- [interpolateEnvVars](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/interpolate-env-vars.md): Interpolate ${VAR|default} patterns in a raw string.
- [load](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/load.md): Load configuration from a JSON file with environment variable interpolation.
- [loadFromObject](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/load-from-object.md): Load configuration from a plain object instead of a file.
- [mergeWithEnv](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/merge-with-env.md): Merge configuration with prefix-matched environment variables.
- [search](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/search.md): Search for a config file in standard locations and load it if found.
- [set](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/set.md): Set a configuration value at a dot-notation path.
- [substituteVars](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/config-loader/substitute-vars.md): Recursively substitute environment variables in any value.
- [Environment Variables](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/environment-variables.md): Complete reference for all environment variables used by the SignalWire Server SDK.
- [Logging](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/logging.md): Structured logging with Logger class and global configuration functions.
- [PromptManager](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager.md): Manages agent prompt text, supporting both raw text and structured POM-based prompts.
- [addSection](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager/add-section.md): Add a POM section to the prompt.
- [addSubsection](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager/add-subsection.md): Add a subsection under a parent POM section.
- [addToSection](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager/add-to-section.md): Append body text or bullets to an existing POM section.
- [getPomBuilder](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager/get-pom-builder.md): Return the underlying PomBuilder instance.
- [getPostPrompt](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager/get-post-prompt.md): Return the post-prompt text.
- [getPrompt](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager/get-prompt.md): Return the fully rendered prompt text.
- [getRawPrompt](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager/get-raw-prompt.md): Return the raw stored prompt text, unrendered.
- [hasSection](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager/has-section.md): Check whether a POM section with the given title exists.
- [setPostPrompt](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager/set-post-prompt.md): Set the post-prompt text appended after the main prompt.
- [setPromptText](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/prompt-manager/set-prompt-text.md): Set raw prompt text, bypassing POM rendering.
- [SchemaUtils](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/schema-utils.md): SWML document validation against structural rules with an LRU-style result cache.
- [clearCache](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/schema-utils/clear-cache.md): Clear the validation result cache.
- [getCacheSize](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/schema-utils/get-cache-size.md): Get the number of cached validation results.
- [getVerbDescription](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/schema-utils/get-verb-description.md): Get the description text for a verb.
- [getVerbNames](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/schema-utils/get-verb-names.md): Get all verb names defined in the SWML schema.
- [getVerbProperties](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/schema-utils/get-verb-properties.md): Get the inner properties schema for a specific verb.
- [getVerbRequiredProperties](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/schema-utils/get-verb-required-properties.md): Get the required properties for a verb.
- [hasVerb](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/schema-utils/has-verb.md): Check if a verb name exists in the schema.
- [validate](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/schema-utils/validate.md): Validate a SWML document against structural rules.
- [validateVerb](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/schema-utils/validate-verb.md): Lightweight validation of a verb config against the schema.
- [ServerlessAdapter](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/serverless-adapter.md): Adapts a Hono application for deployment on AWS Lambda, Google Cloud Functions, Azure Functions, or CGI.
- [createAzureHandler](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/serverless-adapter/create-azure-handler.md): Create an Azure Functions-compatible handler from a Hono app.
- [createGcfHandler](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/serverless-adapter/create-gcf-handler.md): Create a Google Cloud Functions-compatible handler from a Hono app.
- [createLambdaHandler](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/serverless-adapter/create-lambda-handler.md): Create an AWS Lambda-compatible handler from a Hono app.
- [detectPlatform](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/serverless-adapter/detect-platform.md): Detect the serverless platform from environment variables.
- [generateUrl](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/serverless-adapter/generate-url.md): Generate the platform-specific invocation URL for a deployed function.
- [getPlatform](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/serverless-adapter/get-platform.md): Get the resolved platform identifier.
- [handleRequest](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/serverless-adapter/handle-request.md): Route a serverless event through the Hono app and return a normalized response.
- [SessionManager](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/session-manager.md): Stateless HMAC-SHA256 token manager for SWAIG function call authentication and per-session metadata storage.
- [cleanup](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/session-manager/cleanup.md): Remove expired session metadata entries.
- [createSession](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/session-manager/create-session.md): Return the given call ID or generate a new random session identifier.
- [createToolToken](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/session-manager/create-tool-token.md): Alias for generateToken.
- [debugToken](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/session-manager/debug-token.md): Decode token components for inspection without validating the signature.
- [deleteSessionMetadata](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/session-manager/delete-session-metadata.md): Delete all metadata for a session.
- [generateToken](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/session-manager/generate-token.md): Generate a signed, base64url-encoded token binding a function name to a call ID.
- [getSessionMetadata](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/session-manager/get-session-metadata.md): Retrieve metadata associated with a session.
- [setSessionMetadata](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/session-manager/set-session-metadata.md): Merge metadata into a session.
- [validateToken](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/session-manager/validate-token.md): Validate a token against the expected call ID and function name.
- [validateToolToken](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/session-manager/validate-tool-token.md): Alias for validateToken with reordered parameters.
- [SslConfig](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/ssl-config.md): SSL/TLS configuration for HTTPS serving with HSTS support.
- [getCert](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/ssl-config/get-cert.md): Read the PEM certificate file from disk.
- [getHstsHeader](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/ssl-config/get-hsts-header.md): Build the Strict-Transport-Security header value.
- [getKey](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/ssl-config/get-key.md): Read the PEM private key file from disk.
- [getServerOptions](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/ssl-config/get-server-options.md): Create the options object for Node.js https.createServer().
- [hstsMiddleware](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/ssl-config/hsts-middleware.md): Hono middleware that appends HSTS headers to responses.
- [isConfigured](https://signalwire.com/docs/server-sdks/reference/typescript/agents/configuration/ssl-config/is-configured.md): Check whether SSL is fully configured with cert and key files on disk.