Codex Switcher

A lightweight local dashboard for managing Codex model settings, reasoning effort, service tier, and custom OpenAI-compatible API providers from a browser UI.

This project runs locally on your machine and updates your Codex configuration without requiring you to manually edit config.toml.

Features

• Switch Codex models from a local web dashboard
• Change reasoning effort and service tier in real time
• Add and manage custom OpenAI-compatible API providers
• Activate a custom provider through a local proxy
• Automatically create configuration backups before changes
• Restore previous Codex configuration backups
• Mask local user paths in the UI for better privacy
• Keep API credentials local and out of Git

How It Works

Codex Switcher starts a local Express server and serves a browser-based dashboard at:

http://localhost:3777

The app reads and updates your local Codex files:

C:\Users\XXXXX\.codex\config.toml
C:\Users\XXXXX\.codex\models_cache.json
C:\Users\XXXXX\.codex\auth.json

Custom provider data is stored locally in:

providers.json

providers.json is intentionally ignored by Git because it may contain API keys.

Requirements

• Windows
• Node.js 18 or newer
• npm
• Codex installed and configured locally

Installation

Clone the repository:

git clone https://github.com/airplanestar888/Codex-Switcher.git
cd Codex-Switcher

Install dependencies:

npm install

Optional: create a local provider config from the example file:

cp providers.example.json providers.json

Then edit providers.json or add providers from the web dashboard.

Usage

Start the local server:

npm start

Or:

node server.js

Open the dashboard:

http://localhost:3777

On Windows, you can also run:

run swap.bat

Managing OpenAI Models

The dashboard can read available models from your local Codex model cache and display them in the UI. Selecting a model updates your local Codex configuration.

The app updates values such as:

model = "..."
model_reasoning_effort = "..."
service_tier = "..."

Managing Custom Providers

You can add custom OpenAI-compatible providers from the dashboard by entering:

• Provider name
• Base URL
• API key
• Model IDs

Example provider format:

{
  "providers": [
    {
      "id": "example-provider",
      "name": "Example Provider",
      "baseUrl": "https://example.com/v1",
      "apiKey": "YOUR_API_KEY_HERE",
      "models": [
        "example-model"
      ]
    }
  ],
  "activeProviderId": null,
  "activeProviderModel": null
}

When a custom provider is activated, Codex Switcher routes requests through the local proxy:

http://127.0.0.1:3777/v1

The proxy forwards requests to the selected provider and injects the configured API key locally.

Backups

Before modifying your Codex configuration, the app creates a backup in:

C:\Users\XXXXX\.codex\Backup

Only the most recent backups are kept automatically.

You can restore backups directly from the dashboard.

Security Notes

This project is designed to keep sensitive data local.

The following files are ignored by Git:

providers.json
.env
.env.*
node_modules/

Do not commit real API keys, tokens, or personal credentials.

Use providers.example.json as a safe template for sharing provider configuration format.

Project Structure

.
├── public/
│   ├── index.html      # Web dashboard
│   └── style.css       # Dashboard styles
├── server.js           # Express server, API routes, local proxy
├── package.json        # npm scripts and dependencies
├── providers.example.json
├── run swap.bat        # Windows helper script
└── README.md

npm Scripts

npm start
npm run dev

Both scripts start the local server.

Troubleshooting

Dashboard cannot connect to server

Make sure the server is running:

npm start

Then open:

http://localhost:3777

Models are not shown

Make sure Codex has already generated a local model cache at:

C:\Users\XXXXX\.codex\models_cache.json

If no cache exists, the dashboard falls back to a default model display.

Custom provider does not work

Check that:

• The provider Base URL is correct
• The API key is valid
• The selected model ID exists on that provider
• The provider supports OpenAI-compatible chat completions

License

This repository does not currently include a license file. Add one before distributing or using it in production environments.