# How to Configure Custom CORS Headers for Thunderbolt

> Learn how to configure custom CORS headers for Thunderbolt. Set CORS_ALLOW_HEADERS environment variable or modify settings.ts in thunderbird/thunderbolt for easy header management.

- Repository: [Thunderbird/thunderbolt](https://github.com/thunderbird/thunderbolt)
- Tags: how-to-guide
- Published: 2026-04-19

---

**Set the `CORS_ALLOW_HEADERS` environment variable to a comma-separated list of header names before starting the server, or modify the default value in [`backend/src/config/settings.ts`](https://github.com/thunderbird/thunderbolt/blob/main/backend/src/config/settings.ts) to permanently change the allowed headers in the thunderbird/thunderbolt repository.**

Configuring custom CORS headers for Thunderbolt ensures your HTTP server accepts specific request headers required by your application. The thunderbird/thunderbolt repository uses a centralized settings schema that combines environment variables with Zod validation to build the CORS policy. Understanding how these components interact allows you to safely customize header allowances without modifying core application logic.

## Understanding the CORS Configuration Architecture

Thunderbolt's CORS policy is constructed from three interconnected components defined in the source code. The configuration flows from environment variables through a Zod schema into the Fastify middleware layer.

In [`backend/src/config/settings.ts`](https://github.com/thunderbird/thunderbolt/blob/main/backend/src/config/settings.ts), the `corsAllowHeaders` field is defined as a Zod string with a comprehensive default value:

```typescript
corsAllowHeaders: z
  .string()
  .default('Content-Type,Authorization,…,Mcp-Protocol-Version'),

```

During server initialization in [`backend/src/index.ts`](https://github.com/thunderbird/thunderbolt/blob/main/backend/src/index.ts), the Fastify CORS plugin receives `settings.corsAllowHeaders` as its `allowedHeaders` parameter. This configuration is shared across all route modules, including [`proxy.ts`](https://github.com/thunderbird/thunderbolt/blob/main/proxy.ts) and [`link-preview.ts`](https://github.com/thunderbird/thunderbolt/blob/main/link-preview.ts), ensuring consistent header enforcement throughout the application.

## Methods to Configure Custom CORS Headers for Thunderbolt

You can customize the allowed headers using environment variables for flexibility or by modifying the source code for permanent project-wide changes.

### Using Environment Variables (Recommended)

The `CORS_ALLOW_HEADERS` environment variable overrides the default schema value when the server starts. This method is ideal for deployment-specific configurations without code changes.

Create or edit your `.env` file in the project root:

```dotenv
CORS_ALLOW_HEADERS=Content-Type,Authorization,X-Custom-Header,X-Another-Header

```

When the server initializes, `getSettings()` reads this variable and the Fastify CORS middleware will accept your custom headers.

### Command Line Override

For temporary testing or one-off executions, prepend the environment variable to your start command:

```bash
CORS_ALLOW_HEADERS="Content-Type,Authorization,My-Header" bun run start

```

This approach is useful for debugging header issues without modifying configuration files.

### Hard-Coding in Settings

For permanent project-wide changes that apply to all instances, modify the default value in [`backend/src/config/settings.ts`](https://github.com/thunderbird/thunderbolt/blob/main/backend/src/config/settings.ts):

```typescript
corsAllowHeaders: z
  .string()
  .default(
    'Content-Type,Authorization,My-Header,Another-Header',
  ),

```

After rebuilding the application, every server instance will use this new default without requiring environment variables.

## Verifying Your Configuration

To confirm your custom headers are active, inspect the runtime settings using the `getSettings()` function:

```typescript
import { getSettings } from './config/settings';

console.log('Allowed CORS headers:', getSettings().corsAllowHeaders);

```

This output should reflect your environment variable or source code modification. You can also verify behavior by sending a preflight `OPTIONS` request with your custom headers to any endpoint.

## Summary

- Thunderbolt reads CORS headers from the `CORS_ALLOW_HEADERS` environment variable or falls back to a default list defined in [`backend/src/config/settings.ts`](https://github.com/thunderbird/thunderbolt/blob/main/backend/src/config/settings.ts).
- The `corsAllowHeaders` schema value is passed to Fastify's CORS plugin in [`backend/src/index.ts`](https://github.com/thunderbird/thunderbolt/blob/main/backend/src/index.ts), affecting all routes including proxy and link-preview modules.
- Use environment variables for deployment-specific flexibility, or modify the Zod default for permanent project-wide changes.
- Verify configuration by logging `getSettings().corsAllowHeaders` at runtime.

## Frequently Asked Questions

### What is the default value for CORS headers in Thunderbolt?

The default value is defined in [`backend/src/config/settings.ts`](https://github.com/thunderbird/thunderbolt/blob/main/backend/src/config/settings.ts) as a comma-separated string including `Content-Type`, `Authorization`, and `Mcp-Protocol-Version` among other standard headers. This default covers common HTTP and MCP protocol headers required for standard operations.

### Which route modules are affected by the CORS header configuration?

According to the source code, the CORS configuration in [`backend/src/index.ts`](https://github.com/thunderbird/thunderbolt/blob/main/backend/src/index.ts) applies globally to all routes, including those defined in [`backend/src/proxy.ts`](https://github.com/thunderbird/thunderbolt/blob/main/backend/src/proxy.ts) and [`backend/src/link-preview.ts`](https://github.com/thunderbird/thunderbolt/blob/main/backend/src/link-preview.ts). The shared `settings.corsAllowHeaders` value ensures consistent header enforcement across proxy, link-preview, and other API endpoints.

### Can I use wildcards in the CORS_ALLOW_HEADERS environment variable?

No, Thunderbolt treats the `CORS_ALLOW_HEADERS` value as a literal comma-separated list of exact header names. Wildcards are not supported in this configuration string. You must explicitly list each header name you want to allow, such as `X-Custom-Header` or `X-Request-ID`.

### How do I troubleshoot CORS errors in Thunderbolt?

First, verify your configuration by logging `getSettings().corsAllowHeaders` to confirm the server recognizes your custom headers. Check that the browser's preflight `OPTIONS` request matches the allowed headers exactly. If issues persist, inspect [`backend/src/index.ts`](https://github.com/thunderbird/thunderbolt/blob/main/backend/src/index.ts) to ensure the Fastify CORS plugin is receiving the settings correctly and that no route-specific overrides exist.