> This page is for Server SDKs.

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

# WebService

> Static file server with HTTP Basic Auth, extension filtering, CORS, and optional HTTPS.

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

[start]: /docs/server-sdks/reference/typescript/agents/web-service/start

WebService serves static files from one or more local directories, each mounted at a URL route prefix. It supports HTTP Basic Auth, extension allowlists and blocklists, file size limits, CORS, directory browsing, and optional SSL/TLS. Use it when an agent needs to serve supporting assets such as audio files, images, or prompts from the same process.

Every route except `/health` requires HTTP Basic Auth, and [`start()`][start] throws until credentials are configured. Supply them with the `basicAuth` option, the config file's `security.auth.basic`, or the `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD` environment variables.

## Constructor

**`options`** `WebServiceOptions`

Configuration object. Every field is optional. Explicit options override values from the config file.

---

**`options.port`** `number` — default: 8002

Port to bind to.

---

**`options.directories`** `Record<string, string>` — default: \{}

Map of URL route prefixes to local directory paths.

---

**`options.basicAuth`** `[string, string]`

Basic auth credentials as `[username, password]`. Falls back to the config file's `security.auth.basic`, then to the `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD` environment variables. Every route except `/health` requires them. If no password is configured from any of these (an empty one doesn't count), the service refuses every request and `start()` throws.

---

**`options.configFile`** `string`

Path to a JSON config file.

---

**`options.enableDirectoryBrowsing`** `boolean` — default: false

Serve directory listings and fall back to `index.html`.

---

**`options.allowedExtensions`** `string[]`

Allowlist of file extensions, for example `['.html', '.css']`. All extensions are allowed when omitted.

---

**`options.blockedExtensions`** `string[]` — default: \['.env', '.git', '.gitignore', '.key', '.pem', '.crt', '.pyc', '\_\_pycache\_\_', '.DS_Store', '.swp']

Blocklist of file extensions or names. An entry is also refused as the name of any directory on the path below the mount. Whatever this holds, a path with a component below the mount that starts with a dot, other than `.well-known`, is never served.

---

**`options.maxFileSize`** `number` — default: 104857600

Maximum file size in bytes (100 MB by default).

---

**`options.enableCors`** `boolean` — default: true

Enable CORS.

---

**`options.ssl`** `SslOptions`

SSL/TLS configuration. See [`SslConfig`][ssl-config] for the fields.

---

## Properties

**`port`** `number`

Port the service binds to.

---

**`enableDirectoryBrowsing`** `boolean`

Whether directory listings are enabled.

---

**`maxFileSize`** `number`

Maximum file size in bytes that will be served.

---

**`enableCors`** `boolean`

Whether CORS is enabled.

---

**`allowedExtensions`** `string[] | null`

Allowlist of file extensions, or `null` to allow all (subject to the blocklist).

---

**`blockedExtensions`** `string[]`

Blocklist of file extensions and file names.

---

**`directories`** `Record<string, string>`

Map of URL route prefixes to local directory paths.

---

**`sslConfig`** `SslConfig`

The [`SslConfig`][ssl-config] instance used by this service, for inspecting SSL settings after construction. Read-only.

---

## Methods

#### [addDirectory](/docs/server-sdks/reference/typescript/agents/web-service/add-directory)

Add a directory to serve at a URL route prefix.

#### [removeDirectory](/docs/server-sdks/reference/typescript/agents/web-service/remove-directory)

Stop serving a directory.

#### [getApp](/docs/server-sdks/reference/typescript/agents/web-service/get-app)

Get the Hono app for mounting or testing.

#### [start](/docs/server-sdks/reference/typescript/agents/web-service/start)

Start the HTTP or HTTPS service.

#### [stop](/docs/server-sdks/reference/typescript/agents/web-service/stop)

Stop the service and release resources.

## Example

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

const web = new WebService({
  port: 8080,
  directories: { '/audio': './public/audio' },
  basicAuth: ['audio', process.env['AUDIO_PASSWORD'] ?? ''],
  allowedExtensions: ['.mp3', '.wav'],
});

await web.start();
// GET http://host:8080/audio/greeting.mp3
```