Codex Tools Account Manager

Skill by ara.so — Codex Skills collection.

Overview

codex-tools is a React + Tauri desktop application for managing multiple Codex accounts, monitoring usage quotas (5h/1week windows), and providing a local OpenAI-compatible API proxy. It supports account switching, automatic usage tracking, and public network exposure via cloudflared.

Primary use cases:

Manage multiple Codex accounts and switch between them
Monitor usage limits and intelligently select accounts with remaining quota
Run a local /v1 API proxy that routes requests through Codex accounts
Expose the proxy to the internet for tools like Cursor that block private IPs
Automatically restart editors and sync OpenAI tokens after account switching

Installation

macOS

Download the latest .dmg from releases:

# If you get "app is damaged" error:
sudo spctl --master-disable
sudo xattr -r -d com.apple.quarantine /Applications/Codex\ Tools.app

Windows

Download the .msi or .exe installer from releases.

From Source

Requirements: Node.js 20+, Rust stable

git clone https://github.com/170-carry/codex-tools.git
cd codex-tools
npm install
npm run tauri dev

Build production:

npm run tauri build

Account Management

Import Accounts

Method 1: OAuth Login

Click the OAuth login button in the UI
Follow the authentication flow
Account token is automatically imported

Method 2: Upload JSON Files

Import single or multiple .json token files:

{
  "access_token": "your_access_token_here",
  "refresh_token": "your_refresh_token_here",
  "expires_at": 1234567890
}

Method 3: Import from Directory

Point the app to a folder containing multiple .json token files. All valid tokens will be imported in batch.

Method 4: Restore Backup

Import a previously exported accounts.json backup file.

Note: After import, the app restores your current logged-in account to avoid disrupting your active session.

Export Accounts

Export all accounts as accounts.json for backup:

{
  "accounts": [
    {
      "id": "account_id_1",
      "access_token": "token1",
      "refresh_token": "refresh1",
      "plan_type": "Pro",
      "usage_5h": 450,
      "usage_1week": 2000
    }
  ]
}

View Usage

The UI displays:

5h window: Requests used in the last 5 hours
1week window: Requests used in the last 7 days
Plan type: Free/Pro/Business
Last refresh: Timestamp of last usage check

Click "Refresh" to manually update, or wait for automatic refresh (default: every 5 minutes).

Switch Accounts

Select an account from the list
Click "Switch & Launch Codex"
The app will:
- Write the new token to the local Codex config
- Launch the Codex desktop app (or fallback to codex app CLI)
- Optionally sync the OpenAI token to Opencode
- Optionally restart your selected editor (VS Code, Cursor, etc.)

Smart Switch: Click "Smart Switch" to automatically select the account with the most remaining quota in the current window.

API Proxy

The proxy provides an OpenAI-compatible /v1 endpoint backed by Codex accounts.

Start the Proxy

UI:

Navigate to "API Proxy" tab
Click "Start Proxy"
The proxy starts on http://127.0.0.1:8787/v1 (default)

Auto-start: Enable "Start proxy on app launch" in settings.

Configuration

Port:

Default: 8787
Custom: Set in the settings panel

API Key:

Fixed key: Set a static key in settings
Manual refresh: Click "Refresh API Key" to generate a new random key
The key is used for Bearer token authentication

Account Selection: The proxy automatically selects the account with the most remaining quota when handling requests.

Usage Example

# Test the proxy
curl http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

import openai

openai.api_base = "http://127.0.0.1:8787/v1"
openai.api_key = "YOUR_API_KEY"

response = openai.ChatCompletion.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Write a hello world in Rust"}]
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:8787/v1",
  apiKey: process.env.CODEX_PROXY_KEY,
});

const completion = await client.chat.completions.create({
  model: "gpt-5.4",
  messages: [{ role: "user", content: "Explain async/await in JS" }],
});

console.log(completion.choices[0].message.content);

Supported Models

gpt-5.4 (recommended)
gpt-5-4 (alias)

Add custom models in Cursor: Settings → Models → Add or search model

Cursor Integration

Cursor blocks private IP addresses (127.0.0.1, localhost, 192.168.x.x, 10.x.x.x) when used as OpenAI base URLs.

Solution: Use Public URL

Option 1: Cloudflared (Built-in)

Navigate to "Public Access" tab
Click "Start Cloudflared"
Copy the generated public URL (e.g., https://abc123.trycloudflare.com)
In Cursor:
- Settings → Models
- Enable "OpenAI API Key", paste your proxy API key
- Enable "Override OpenAI Base URL", paste https://abc123.trycloudflare.com/v1
- Add custom model gpt-5.4

Option 2: Named Tunnel

Configure a named cloudflared tunnel for a persistent URL:

# cloudflared config.yml
tunnel: your-tunnel-id
credentials-file: /path/to/credentials.json

ingress:
  - hostname: codex.yourdomain.com
    service: http://127.0.0.1:8787
  - service: http_status:404

Option 3: Remote Reverse Proxy

Deploy a reverse proxy on a public server:

# nginx.conf
server {
    listen 443 ssl;
    server_name codex.yourdomain.com;

    location /v1 {
        proxy_pass http://your-local-ip:8787/v1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Cursor Configuration

Open Cursor → Settings → Models
Enable "OpenAI API Key", enter your proxy API key
Enable "Override OpenAI Base URL", enter your public URL with /v1
In "Add or search model", type gpt-5.4 and click "Add Custom Model"
Test by asking a question in Cursor chat

Cloudflared Public Access

Quick Tunnel

No configuration required. Generates a random .trycloudflare.com URL:

Click "Start Quick Tunnel"
URL appears in the UI (e.g., https://random-words-123.trycloudflare.com)
Share this URL or use in Cursor

Named Tunnel

Requires a Cloudflare account and tunnel setup:

Create a tunnel at Cloudflare Zero Trust
Download credentials JSON
In codex-tools: Settings → Cloudflared → Named Tunnel
Upload credentials and configure hostname
Click "Start Named Tunnel"

HTTP/2 Support

Enable HTTP/2 in settings for better performance with streaming responses.

Editor Integration

Restart Editor After Switch

Enable in Settings → Editor:

VS Code
Cursor
Other (specify process name)

When you switch accounts, the app will:

Kill the editor process
Wait 2 seconds
Restart the editor

Sync OpenAI Token to Opencode

Enable in Settings → Integrations:

Automatically sync the Codex OpenAI token to Opencode config
Useful if you use both tools in parallel

CC Switch Integration

codex-tools can act as a custom provider for CC Switch:

{
  "providers": [
    {
      "name": "codex-local",
      "type": "custom",
      "base_url": "http://127.0.0.1:8787/v1",
      "api_key": "${CODEX_PROXY_KEY}",
      "protocol": "responses"
    }
  ]
}

The proxy follows the responses protocol for account selection and load balancing.

Troubleshooting

"App is Damaged" on macOS

sudo spctl --master-disable
sudo xattr -r -d com.apple.quarantine /Applications/Codex\ Tools.app

Cursor Shows `ssrf_blocked` Error

This means Cursor is blocking private IPs. Use a public URL via cloudflared or a reverse proxy (see "Cursor Integration").

Proxy Not Starting

Check if port 8787 is already in use: lsof -i :8787
Try a different port in settings
Ensure you have at least one valid account imported

Account Import Fails

Verify JSON structure matches the expected format
Check token expiry: expires_at should be in the future
Re-authenticate via OAuth if refresh token is expired

Usage Not Updating

Click "Refresh" manually
Check network connectivity
Verify account tokens are still valid (re-login if needed)

Cloudflared Tunnel Fails

Ensure cloudflared binary is installed and accessible
For named tunnels, verify credentials file path
Check Cloudflare dashboard for tunnel status

Editor Not Restarting

Verify the editor process name in settings matches the actual process
On macOS, grant codex-tools accessibility permissions if needed
Try manually killing and restarting the editor

Configuration Files

Account Storage

Accounts are stored in the Tauri app data directory:

macOS: ~/Library/Application Support/com.codex-tools.app/
Windows: %APPDATA%/com.codex-tools.app/
Linux: ~/.local/share/com.codex-tools.app/

Settings

Settings are persisted in the same directory as settings.json:

{
  "proxy_port": 8787,
  "api_key": "your-static-key",
  "auto_start_proxy": true,
  "editor": "cursor",
  "restart_editor_on_switch": true,
  "sync_opencode": false,
  "cloudflared_http2": true,
  "language": "en"
}

Development

Project Structure

codex-tools/
├── src/               # React frontend
│   ├── components/    # UI components
│   ├── hooks/         # React hooks
│   └── lib/           # Utilities
├── src-tauri/         # Rust backend
│   ├── src/
│   │   ├── main.rs    # Entry point
│   │   ├── proxy.rs   # API proxy logic
│   │   ├── accounts.rs # Account management
│   │   └── cloudflared.rs # Cloudflared integration
│   └── Cargo.toml
└── package.json

Adding a New Feature

Define Tauri command in src-tauri/src/main.rs:

#[tauri::command]
async fn my_new_feature(param: String) -> Result<String, String> {
    // Implementation
    Ok(format!("Processed: {}", param))
}

fn main() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![my_new_feature])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Call from React frontend:

import { invoke } from "@tauri-apps/api/tauri";

const result = await invoke<string>("my_new_feature", { param: "test" });
console.log(result);

Running Tests

# Rust tests
cd src-tauri
cargo test

# Frontend tests (if configured)
npm test

Release Process

Releases are automated via GitHub Actions. To trigger a release:

git tag v0.2.0
git push origin v0.2.0

Builds for macOS (Intel + ARM) and Windows will be created automatically.

License

MIT License. See LICENSE.

codex-tools-account-manager