Team-wide Codex setup with remote Headroom Proxy and Azure AI Foundry

[ramido99]

We are trying to build an internal team setup where developers can use Codex for AI-assisted coding through a shared remote Headroom Proxy, which then connects to Azure AI Foundry / Azure OpenAI.

Target architecture:

Developers' local PCs running Codex
-> Remote Headroom Proxy container
-> Azure AI Foundry / Azure OpenAI API

Our goals are:

1. Developers should run Codex locally on their own PCs.

2. Codex should connect to a remote Headroom Proxy using a custom Codex profile, for example:

   codex --profile headroom

3. The remote Headroom Proxy should optimize/compress context before forwarding requests.

4. The upstream model provider should be Azure AI Foundry / Azure OpenAI.

5. Azure endpoint and API key information should be managed only on the remote server side.

6. Developers should not have direct access to Azure API keys.

7. The setup should support Codex coding workflows, including Responses API streaming.

8. We want to use this internally within our development team for vibe coding / AI-assisted development.

Current architecture we are testing:

Codex on developer PC
-> Remote Headroom Proxy container
-> Azure adapter or proxy layer if needed
-> Azure AI Foundry / Azure OpenAI API

Questions:

1. Is this architecture supported or recommended?

2. What is the correct configuration for Codex custom provider profiles when using a remote Headroom Proxy?

3. Can Headroom Proxy directly forward requests to Azure AI Foundry / Azure OpenAI?

4. Does Headroom support Azure OpenAI API key authentication directly, including Azure's required api-key header?

5. If Azure requires an adapter layer, what is the recommended architecture?

6. Are there known issues with Codex custom providers and Responses API streaming?

7. Why would simple curl requests to Headroom or Azure succeed, while Codex fails with errors like:

   • Model metadata not found
   • Stream disconnected before completion
   • stream closed before response.completed

8. How should model metadata be configured when Codex uses Azure deployment names?

9. Is there a known working reference configuration for:

   Codex
   -> Headroom Proxy
   -> Azure AI Foundry / Azure OpenAI

10. If this architecture is not currently reliable, what is the recommended alternative for a team-wide Codex + Azure AI Foundry setup where Azure API keys are centrally managed and not exposed to developers?

We would appreciate a working example configuration for:

• Codex config.toml or profile config
• Headroom Proxy Docker Compose configuration
• Azure AI Foundry / Azure OpenAI integration
• Any required adapter or gateway layer

[richardchen874-sys]

This is a very practical team-wide setup question.

I would separate the problem into three layers:

1. Codex client compatibility
   Codex needs a provider profile that matches the API surface it expects, especially if the workflow depends on Responses API streaming. A simple curl success does not always mean the Codex client will work, because Codex also needs model metadata, streaming lifecycle events, and response completion semantics.

2. Headroom proxy behavior
   The remote proxy needs to preserve the API shape expected by Codex while adding compression/optimization. If it changes streaming events, model names, usage fields, or completion markers, Codex may fail with errors like stream disconnected before completion or stream closed before response.completed.

3. Azure adapter compatibility
   Azure OpenAI / Azure AI Foundry has its own deployment names, auth headers, endpoint shape, and API-version requirements. If Headroom expects OpenAI-style Authorization: Bearer ... but Azure expects api-key, then an adapter layer or header translation layer may be needed.

The model metadata issue is probably especially important. Codex may be asking for metadata using the model name in the local profile, while Azure expects a deployment name. The proxy may need a mapping layer like:

codex model name -> proxy model alias -> Azure deployment name

A few things I would verify:

• whether Codex is sending Chat Completions or Responses API requests
• whether Headroom supports that exact API surface
• whether streaming events preserve response.completed
• whether the proxy returns model metadata in the shape Codex expects
• whether Azure deployment names are mapped to user-facing model aliases
• whether Azure api-key auth is translated correctly
• whether API version is fixed in the Azure upstream URL
• whether usage/token fields are preserved after compression
• whether failed streams are caused by Azure, Headroom, or Codex client parsing

For this architecture, I would avoid exposing Azure keys to developers. A centralized proxy/gateway is the right direction for a team, but it needs clear boundaries:

Codex profile → Headroom-compatible endpoint → Azure adapter → Azure deployment

If Headroom does not natively support Azure’s header/auth/deployment shape yet, the safest interim design may be to put a small Azure adapter behind Headroom, or use a gateway layer that normalizes Azure into the exact OpenAI/Responses API shape Codex expects.