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

> Configure SSL/TLS for Headroom in corporate proxy environments by setting environment variables like SSL_CERT_FILE to enable TLS verification.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-14

---

**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:

```bash
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:

```bash
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:

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

```

## The `find_ca_bundle()` Implementation

In [`headroom/proxy/ssl_context.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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:
   
   ```bash
   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:

```bash
#!/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:

```python
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:

```ts
// 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:

```python
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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/server.py) around line 153, where the server calls `find_ca_bundle()` from [`headroom/proxy/ssl_context.py`](https://github.com/chopratejas/headroom/blob/main/headroom/proxy/ssl_context.py) during startup. This happens before any outbound connections to AI providers are established.