Codex DS4 Bridge

Run Codex against local DeepSeek V4 Flash served by antirez/ds4, with an optional isolated macOS app launcher.

This is a proof of concept, not an official Codex or DS4 integration. It is shared so other people with high-memory Apple Silicon machines can reproduce it, improve it, or fork it into something cleaner.

Credit Where It Belongs

This project is a companion bridge. The hard and important work is ds4.c by Salvatore Sanfilippo / Antirez: a focused Apple Silicon Metal inference engine for DeepSeek V4 Flash.

If this bridge is useful, it is because ds4 already does the difficult part: loading the supported DeepSeek V4 Flash GGUFs, running the model locally, and exposing an OpenAI-style server. Please star, read, and credit the original project.

This repo only adds:

• a small Codex Responses API proxy
• a local web UI for quick testing
• Codex CLI launch scripts
• an isolated macOS app wrapper so experiments do not share normal Codex state
• setup notes aimed at people who have the hardware but do not live in local inference tooling every day

Current Status

Reliable path:

• Codex CLI -> local proxy -> ds4-server -> DeepSeek V4 Flash

Experimental path:

• Codex DS4 Isolated.app -> isolated Codex Desktop process -> local proxy -> ds4-server

The Desktop model picker may still show the normal hosted model name. The proof is the proxy request log. If a Codex turn writes POST /v1/responses to harness/logs/codex-proxy-requests.log, that request went through the DS4 bridge.

Important Performance Warning

The isolated Codex Desktop path works, but it is not fast like hosted Codex.

Codex Desktop sends a large prompt envelope even in chat-only mode. In local testing on a 128 GB M5 Max using the q2 DS4 model:

• lightweight DS4 web UI prompt: about 1.2k prompt tokens
• isolated Codex Desktop chat prompt: about 5.7k to 8.6k prompt tokens after tool forwarding was disabled
• full Codex/tool mode: about 20k+ prompt tokens in observed turns

DS4 prefill on this machine was roughly 285-315 tokens/sec, and generation was roughly 23-31 tokens/sec. That means a large Codex prompt can spend tens of seconds in prefill before the first visible token.

The bridge therefore has two practical modes:

• Fast chat / default: tools are not forwarded. This is usable as a local DS4 chat interface inside Codex Desktop, but it is not the full Codex agent experience.
• Full tool experiment: set DS4_CODEX_FORWARD_TOOLS=1 before starting the proxy. This is more Codex-like, but prefill and tool-call latency can be very slow.

The included lightweight web UI is the best way to measure DS4 itself without Codex overhead.

Hardware

This is for high-memory Apple Silicon Macs.

The upstream DS4 README lists:

• ./download_model.sh q2 for 128 GB RAM machines
• ./download_model.sh q4 for 256 GB or larger machines

This bridge defaults to a conservative context window:

DS4_CTX=32768
DS4_KV_MB=8192

That is intentionally modest. Get the baseline working first, then raise DS4_CTX later if your machine has headroom.

Requirements

• macOS on Apple Silicon
• 128 GB unified memory for the q2 model
• Codex CLI / Codex Desktop installed
• Node.js 20 or newer
• git, make, curl
• enough free disk space for the model and KV cache

Quick Start

Clone and build DS4 first:

git clone https://github.com/antirez/ds4.git
cd ds4
./download_model.sh q2
make

Clone this bridge somewhere else:

git clone https://github.com/atomtanstudio/codex-ds4-bridge.git
cd codex-ds4-bridge

Install the harness into your DS4 checkout:

./scripts/install-into-ds4.sh /path/to/ds4

Start Codex CLI through DS4:

cd /path/to/ds4
./harness/start-codex-ds4-cli.sh

That script starts ds4-server if needed, starts the Codex proxy if needed, and launches:

codex --oss --local-provider lmstudio -m deepseek-v4-flash

with:

CODEX_OSS_BASE_URL=http://127.0.0.1:8788/v1
CODEX_HOME=~/.codex-ds4/codex-home
model_provider=ds4

The isolated Desktop config defines [model_providers.ds4] with base_url = "http://127.0.0.1:8788/v1" and wire_api = "responses".

By default the proxy does not forward Codex tool schemas to DS4. This makes simple chat much faster and avoids local DS4 spending a long time generating tool calls for normal prompts. To experiment with full agent/tool mode, start the proxy with:

DS4_CODEX_FORWARD_TOOLS=1 ./harness/start-codex-proxy.sh

Optional: Create the Isolated macOS App

After installing the harness into DS4:

./scripts/create-macos-app.sh /path/to/ds4

That creates:

/Applications/Codex DS4 Isolated.app

The app uses isolated state:

~/.codex-ds4/codex-home
~/.codex-ds4/electron-user-data

It refuses to launch if those paths are accidentally pointed at your normal Codex state.

The launcher intentionally does not override HOME. macOS Keychain expects the real user home, and faking it can trigger scary keychain reset prompts.

The app icon is included in assets/CodexDS4.icns and is copied into the generated app bundle.

Verify It Is Really Using DS4

In another terminal:

tail -f /path/to/ds4/harness/logs/codex-proxy-requests.log

When Codex uses DS4, you should see:

POST /v1/responses

You can also run a CLI smoke test after DS4 and the proxy are running:

./scripts/smoke-test-cli.sh /path/to/ds4

Expected answer:

ready

Verify Desktop Isolation

Before claiming the isolated Desktop app is safe on a machine, snapshot normal Codex state:

./scripts/verify-isolation.sh snapshot

Then launch Codex DS4 Isolated.app, send one small prompt, quit it, and run:

./scripts/verify-isolation.sh check

See docs/VERIFY_ISOLATION.md.

Local Web UI

The harness also includes a tiny web UI:

cd /path/to/ds4/harness
./start-ui.sh

Open:

http://127.0.0.1:8787

Safety Notes

Do not point DS4 experiments at your normal Codex home:

~/.codex
~/Library/Application Support/Codex

This bridge uses ~/.codex-ds4 for the DS4 path so the regular Codex app can keep its own projects, model picker, and account state.

The scripts also avoid installing a DS4 profile into your normal ~/.codex/config.toml.

Troubleshooting

Check DS4:

curl http://127.0.0.1:8000/v1/models

Check the Codex proxy:

curl http://127.0.0.1:8788/v1/models

Watch logs:

tail -f /path/to/ds4/harness/logs/ds4-server.log
tail -f /path/to/ds4/harness/logs/codex-proxy.log
tail -f /path/to/ds4/harness/logs/codex-proxy-requests.log

License

This bridge is MIT licensed.

ds4 is a separate upstream project. Follow its license and model-weight instructions.