GitHub - ryanzhou/dsv4-codex-proxy

Dsv4 Codex Proxy makes DeepSeek V4 Flash 0731 work as a first-class model in Codex. Codex speaks the OpenAI Responses API, while most inference providers are chat-completions native and commonly expose the Responses API only as a thin translation layer on top. Dsv4 Codex Proxy instead uses the low-level Completions API directly, which requires Completions API support that not all inference providers offer. It applies a DeepSeek chat template designed specifically for Codex's tools, reasoning, and stateful agent workflows.

Codex  <-- Responses API over WebSocket or HTTP -->  Proxy  <-- /v1/completions -->  Inference engine

The upstream must provide an OpenAI-compatible streaming Completions endpoint. For developers hosting the model locally, vLLM support enables strict mode, which uses constrained decoding for improved tool-calling performance; other inference servers work in the default portable mode.

Features

Comparison with DeepSeek's official Codex integration

DeepSeek publishes an official Codex integration (docs) that points Codex directly at the hosted DeepSeek Responses API. Dsv4 Codex Proxy targets a different niche: it adapts Codex to DeepSeek V4 Flash through any OpenAI-compatible Completions endpoint, including self-hosted inference. The matrix summarizes what each setup supports.

✅ supported · ❌ not offered · ⚠️ experimental/partial

Quick start with Docker

docker run --rm --name dsv4-codex-proxy \
  -p 4000:4000 \
  -e UPSTREAM_URL=https://inference.example.com/v1/completions \
  -e UPSTREAM_MODEL=deepseek-ai/DeepSeek-V4-Flash-0731 \
  -e UPSTREAM_API_KEY=your-upstream-key \
  ghcr.io/ryanzhou/dsv4-codex-proxy:latest

UPSTREAM_API_KEY can be omitted when the inference endpoint does not require credentials. Confirm the proxy is ready:

curl http://127.0.0.1:4000/healthz

Configure Codex

Download the bundled model catalog somewhere Codex can read it:

mkdir -p ~/.codex
curl -fsSL \
  https://raw.githubusercontent.com/ryanzhou/dsv4-codex-proxy/main/model-catalog.json \
  -o ~/.codex/deepseek-v4-flash-model-catalog.json

Add the provider to ~/.codex/config.toml. model_catalog_json must be an absolute path:

model = "deepseek-v4-flash"
model_provider = "dsv4-codex-proxy"
model_catalog_json = "/home/you/.codex/deepseek-v4-flash-model-catalog.json"
model_reasoning_effort = "high"
model_reasoning_summary = "none"

[model_providers.dsv4-codex-proxy]
name = "Dsv4 Codex Proxy"
base_url = "http://127.0.0.1:4000/v1"
wire_api = "responses"
supports_websockets = true

Start Codex normally:

Unified exec is enabled by default in current Codex releases. No OpenAI API key is required for the local provider; UPSTREAM_API_KEY belongs only to the proxy-to-inference-server connection.

Ultra and multi-agent V2

Set the reasoning effort to Ultra:

model_reasoning_effort = "ultra"

The bundled catalog selects multi-agent V2, so no separate feature flag is required. Codex maps Ultra inference to maximum reasoning and injects its proactive delegation policy; agent creation and orchestration remain local to Codex.

Code mode

The proxy supports Codex's code-mode exec custom tool. To make code mode the only tool surface, change the catalog entry:

"tool_mode": "code_mode_only"

Direct mode is the default; code mode is available to evaluate side by side against your workload.

vLLM strict mode

Strict mode constrains generation after DeepSeek begins a DSML tool block. It limits tool names and arguments to the schemas Codex supplied, including custom tool grammars and parallel calls:

This mode uses vLLM's structured-output extension. Leave it off for other inference providers.

Hosted web search

Enable the Firecrawl adapter:

WEB_SEARCH_ADAPTER=firecrawl
FIRECRAWL_API_KEY=fc-your-key

Then set web_search = "live" in Codex. Search state and results stay in the Responses conversation and are available to later turns.

Reasoning summaries

Reasoning remains preserved for subsequent model turns regardless of this setting. To additionally show short progress headings in the Codex UI:

The proxy uses the same upstream Completions endpoint to summarize roughly every 2,000 characters of reasoning. This is off by default.

Configuration

Responses are available at /v1/responses and /responses over WebSocket or streaming HTTP. Health checks use /healthz.

Inference providers with a Completions API

These providers advertise an OpenAI-compatible Completions endpoint, which is all this proxy needs to connect to. We haven't tested them ourselves yet, so please double-check the current details with each provider before you rely on them.

This list is not exhaustive.

Run from source

Erlang and Elixir versions are pinned in .tool-versions:

mise install
mise exec -- mix deps.get
UPSTREAM_URL=https://inference.example.com/v1/completions \
  mise exec -- mix run --no-halt

Development

mise exec -- mix format --check-formatted
mise exec -- mix compile --warnings-as-errors
mise exec -- mix test

docker build -t dsv4-codex-proxy .

Pushes to main and version tags publish ghcr.io/ryanzhou/dsv4-codex-proxy; pull requests build the image without publishing it.

Project status

This is an independent research project, not an official DeepSeek or OpenAI product. DeepSeek V4 Flash behavior can vary between inference engines and sampling configurations, so validate agent settings against your workload.

Limitations

• The upstream must provide an OpenAI-compatible streaming Completions endpoint (not the Chat Completions API), which not all inference providers offer.
• Configuration is single-tenant, read from environment variables at startup.
• The proxy does not authenticate incoming clients. Keep it on a trusted network or place it behind an authenticated reverse proxy before exposing it remotely.

License

Copyright © 2026 Ryan Zhou.

Dsv4 Codex Proxy is free software licensed under the GNU Affero General Public License, version 3 or later.