Shimex - local provider gateway for Codex Desktop.

Q: Does Shimex modify the original Codex app?

No. Shimex creates a managed app copy and isolated profile, leaving the original Codex Desktop installation untouched.

Q: Where do API keys live?

Provider secrets live in a local git-ignored .env file and are referenced from shimex.yml by environment variable name.

Shimex sits between Codex Desktop and any LLM provider — Anthropic, DeepSeek, Ollama, LM Studio, Cloudflare Workers AI, ClinePass — behind an OpenAI-compatible HTTP daemon. Your original Codex install is never modified.

GitHub →

Pricing Free local gateway. Bring your own provider keys or local models. CLI Install, sync, start, stop, and inspect Shimex from npm scripts. Documentation How Shimex manages Codex Desktop, providers, models, and secrets. FAQ Answers about app safety, supported providers, and API keys.

Shimex admin control plane showing providers, models, and managed-app controls — The local admin control plane at `http://127.0.0.1:18765/admin`.

What it does

Copies your real /Applications/Codex.app into a managed Shimex.app with an isolated profile and model catalog. The original Codex app stays untouched.
Exposes an OpenAI-compatible gateway at http://127.0.0.1:18765/v1: /v1/chat/completions, /v1/responses, /v1/models, and a Codex picker catalog.
Normalises Anthropic Messages, OpenAI Responses, OpenAI Chat, and Cursor Composer behind the same inbound shape. Streaming SSE everywhere; non-streaming upstreams are wrapped in a single-chunk SSE so the consumer always sees SSE.
Discovers models dynamically with a written cache. Catalog reads don’t require a live network call; refresh is best-effort on startup.
Holds capabilities to what each provider can actually do. Text-only models reject image input with a typed error instead of dropping parts silently.
Keeps secrets out of source. API keys live in the git-ignored .env and are referenced via auth: { type: env, name: … }.

Pricing

Shimex is a local gateway. It does not add a usage meter or hosted subscription layer.

Free local app

Run the Shimex daemon and managed Codex app on your machine.

Bring your provider

Use your own API keys, ClinePass session, LM Studio server, Ollama models, or other configured endpoints.

Install

macOS with Codex Desktop installed at /Applications/Codex.app, Node 20+, npm 10+.

git clone <repo-url> ~/Projects/shimex
cd ~/Projects/shimex
npm install
cp .env.example .env   # add your API keys; .env is git-ignored
npm start              # prepares Shimex.app, launches the daemon at :18765

Then open the managed Shimex.app and the admin UI at http://127.0.0.1:18765/admin.

CLI

Run Shimex from npm. These commands manage the daemon, inspect health, and list configured provider models.

npm run status                                 # PID, log path, health
npm run shimex -- doctor                       # prerequisite check
npm run shimex -- providers list               # configured providers
npm run shimex -- models list                  # discovered models

Documentation

Shimex is configured by shimex.yml and a local git-ignored .env. The managed app copy, isolated Codex profile, model catalog, and local gateway are all created from those files.

Managed Codex app

Shimex copies Codex Desktop into a managed app and points that copy at the local gateway.

Provider adapters

Adapters translate provider-specific request, response, model, and streaming behavior into Codex-ready shapes.

FAQ

Does Shimex modify the original Codex app?

No. Shimex creates a managed app copy and isolated profile so the original Codex Desktop installation stays untouched.

Which providers can Shimex use?

Shimex can route to ClinePass, DeepSeek, LM Studio, Cloudflare Workers AI, Anthropic, Ollama, Cursor Composer, OpenAI-compatible endpoints, and other configured providers.

Where do API keys live?

Provider secrets live in a local .env file that is ignored by git. shimex.yml references those secrets by environment variable name.