How to Configure Custom CORS Headers for Thunderbolt

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 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, the corsAllowHeaders field is defined as a Zod string with a comprehensive default value:

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

During server initialization in 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 and 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:

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:

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:

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:

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.
• The corsAllowHeaders schema value is passed to Fastify's CORS plugin in 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 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 applies globally to all routes, including those defined in backend/src/proxy.ts and 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 to ensure the Fastify CORS plugin is receiving the settings correctly and that no route-specific overrides exist.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}