How to Configure SSL/TLS for Corporate Proxy Environments in Headroom

Export SSL_CERT_FILE, REQUESTS_CA_BUNDLE, or NODE_EXTRA_CA_CERTS to point to your corporate CA bundle before starting the Headroom proxy to enable TLS verification behind corporate MITM proxies.

Headroom's proxy component uses httpx.AsyncClient for outbound connections to AI providers like OpenAI, Anthropic, and Gemini. When running behind corporate proxies that perform SSL inspection, the library must trust custom root certificates to validate TLS connections. This guide explains how to configure SSL/TLS for corporate proxy environments in Headroom using standard environment variables and the built-in find_ca_bundle() helper.

How Corporate SSL Inspection Affects Headroom

Corporate networks often deploy MITM (Man-in-the-Middle) proxies that intercept and inspect TLS traffic. These proxies present certificates signed by an internal Certificate Authority (CA) rather than public CAs. Without trusting this corporate CA, Headroom's HTTP client will reject connections to AI APIs with SSL verification errors. The repository automatically detects and loads custom CA bundles through specific environment variables, eliminating the need to modify source code.

Environment Variables Headroom Recognizes

The headroom.proxy.ssl_context.find_ca_bundle() function checks for three standard environment variables in order of precedence. The first variable that points to an existing file wins.

SSL_CERT_FILE (Python Standard)

SSL_CERT_FILE is the generic Python SSL variable honored by the standard library's ssl module. Set this to the absolute path of your corporate PEM bundle:

export SSL_CERT_FILE=/etc/ssl/certs/corp-ca.pem

REQUESTS_CA_BUNDLE (Requests Library Compatibility)

REQUESTS_CA_BUNDLE provides compatibility with the widely-used requests library. Many Python developers already have this set for other corporate tools:

export REQUESTS_CA_BUNDLE=/etc/ssl/certs/corp-ca.pem

NODE_EXTRA_CA_CERTS (Node.js Compatibility)

NODE_EXTRA_CA_CERTS is honored by Node.js tools and the TypeScript SDK. This ensures consistency when running Headroom alongside JavaScript tooling:

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corp-ca.pem

The find_ca_bundle() Implementation

In headroom/proxy/ssl_context.py, the find_ca_bundle() function iterates through the three variables above in sequence. When it finds a file that exists, it returns the path string; otherwise, it returns None. According to the source code in headroom/proxy/server.py (line 153), the proxy server calls this function during startup and passes the result to httpx.AsyncClient if a bundle is found. If no variable is set, Headroom falls back to the system's default trust store.

Step-by-Step Configuration

Follow these steps to configure SSL/TLS for corporate proxy environments:

1. Obtain the corporate root CA certificate from your IT security team, usually as a PEM-encoded file.

2. Place the file on the host running Headroom, ensuring the process has read permissions (e.g., /etc/ssl/certs/corp-ca.pem).

3. Export one of the recognized environment variables pointing to that file. You can set all three for safety; Headroom uses the first one that exists:

   export SSL_CERT_FILE=/etc/ssl/certs/corp-ca.pem
   export REQUESTS_CA_BUNDLE=$SSL_CERT_FILE
   export NODE_EXTRA_CA_CERTS=$SSL_CERT_FILE

4. Start the Headroom proxy using the CLI or programmatic API. The proxy automatically detects the bundle during initialization.

5. Verify the configuration by checking logs for the ssl_ca_bundle_loaded event or testing connectivity with headroom proxy --dry-run.

Code Examples

Bash Startup Script

Create a startup script that sets the environment before launching the proxy:

#!/usr/bin/env bash

# Path to the corporate CA bundle

export SSL_CERT_FILE=/etc/ssl/certs/corp-ca.pem
export REQUESTS_CA_BUNDLE=$SSL_CERT_FILE

# Start the Headroom proxy on default port 8787

headroom proxy

Python Programmatic Usage

When embedding the proxy in a Python application:

import os
from headroom.proxy.server import create_app

# Point the HTTP client to the corporate CA bundle

os.environ["SSL_CERT_FILE"] = "/etc/ssl/certs/corp-ca.pem"

# Build the FastAPI app (automatically loads find_ca_bundle())

app = create_app()

# Run with uvicorn, e.g., uvicorn.run(app, host="0.0.0.0", port=8787)

TypeScript SDK Configuration

For Node.js or TypeScript implementations:

// Set the Node.js variable before importing the SDK
process.env.NODE_EXTRA_CA_CERTS = "/etc/ssl/certs/corp-ca.pem";

import { HeadroomProxy } from "headroom-ai";
const proxy = new HeadroomProxy(); // TLS context picks up the CA automatically
await proxy.start();

Verifying the Configuration

Test that the CA bundle detection works correctly:

from headroom.proxy.ssl_context import find_ca_bundle
import os
import tempfile

# Create a temporary CA bundle file

with tempfile.NamedTemporaryFile(delete=False, mode='w') as tmp:
    tmp.write("---FAKE PEM FOR TESTING---")
    tmp_path = tmp.name

os.environ["SSL_CERT_FILE"] = tmp_path
assert find_ca_bundle() == tmp_path
print("CA bundle detected successfully")

Summary

• Headroom automatically detects corporate CA bundles through three standard environment variables: SSL_CERT_FILE, REQUESTS_CA_BUNDLE, and NODE_EXTRA_CA_CERTS.
• The find_ca_bundle() function in headroom/proxy/ssl_context.py checks these variables in order and returns the first valid path.
• When a bundle is found, headroom/proxy/server.py configures the httpx.AsyncClient to trust the corporate CA during proxy startup.
• No code changes are required; simply set the appropriate environment variable before starting the proxy.
• Look for the ssl_ca_bundle_loaded log entry to confirm successful configuration.

Frequently Asked Questions

What if multiple environment variables are set?

Headroom checks the variables in the order SSL_CERT_FILE, then REQUESTS_CA_BUNDLE, then NODE_EXTRA_CA_CERTS. The first one that exists and points to a valid file is used. You can safely set all three to ensure compatibility across different tools.

Does Headroom work without a custom CA bundle?

Yes. If none of the environment variables are set, Headroom falls back to httpx's default system trust store. This works for standard installations without corporate SSL inspection, but will fail if your network intercepts TLS traffic with an internal CA.

How do I verify that Headroom loaded my corporate CA?

Check the proxy logs for an INFO-level log entry containing event=ssl_ca_bundle_loaded. This confirms that find_ca_bundle() located your file and that headroom/proxy/server.py successfully injected it into the HTTP client configuration.

Where is the SSL context initialized in the codebase?

The initialization occurs in headroom/proxy/server.py around line 153, where the server calls find_ca_bundle() from headroom/proxy/ssl_context.py during startup. This happens before any outbound connections to AI providers are established.

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