🚀 codextui

🖥️ A standalone local Codex workspace for account orchestration, OAuth flows, API key management, and terminal-native control

✨ Local-first · 🔐 OAuth-ready · 🧩 Standalone · 🖥️ CLI + TUI + Daemon

---

✨ Overview

codextui is now a fully standalone local project. It no longer depends on codex-lb as a backend service.

While it borrows ideas from codex-lb for:

• 🔑 account importing
• 🔐 OAuth flows
• 🪪 API key management

the rest is owned and maintained by this project itself:

• 📁 its own data directory
• 🧠 its own control logic
• 🖱️ its own interaction model
• 🚪 its own startup entrypoints
• ⚙️ its own local daemon runtime

In practice, codextui is a local Codex control workspace built for managing accounts, API keys, OAuth state, and runtime settings through either a terminal shell, a full-screen dashboard, or a long-running daemon.

---

🌟 Why codextui?

🧩 Fully standalone

No hard dependency on codex-lb. Persistence, control flow, and runtime behavior live inside this project.

💾 Local-first persistence

Accounts, keys, and settings are stored locally and survive restarts.

🔐 OAuth built in

Browser flow, device flow, manual callback handling, and polling are all supported.

🖥️ Multiple operating modes

Run it as:

• 💬 CLI shell
• 🧭 Dashboard TUI
• ⚙️ Daemon service

📂 Flexible import model

Import a single auth.json, or recursively scan a directory for auth.json / *.json.

🔑 Full API key lifecycle

Create, update, enable, disable, reset, and delete keys from local control surfaces.

🐳 Docker-friendly

Keep a daemon alive 24/7 and attach local CLI/TUI clients at any time.

---

✅ Current capabilities

Current versions of codextui already support:

• ✅ local persistent storage for accounts, API keys, and settings
• ✅ startup mode selection: CLI shell, Dashboard TUI, or Daemon service
• ✅ single-file auth.json import
• ✅ recursive batch import for auth.json / *.json
• ✅ OAuth browser flow
• ✅ OAuth device flow
• ✅ manual callback handling
• ✅ device polling
• ✅ pause / resume / delete account operations
• ✅ create / update / enable / disable / reset / delete API keys
• ✅ local settings management
• ✅ daemon mode for long-running local or Docker deployments
• ✅ remote CLI/TUI clients connecting to daemon backends

---

🏗️ Tech stack

codextui is built on a terminal-first Python stack:

• 🐍 Python 3.11+
• 🖼️ Textual — full-screen TUI framework
• 🎨 Rich — terminal rendering and formatting
• ⌨️ prompt_toolkit — interactive command shell experience
• 🌐 httpx — persistent HTTP sessions
• 📦 pydantic — validated data models

---

📦 Installation

Recommended: create a virtual environment first, then install in editable mode.

cd codextui
python3 -m venv .venv
.venv/bin/pip install -e .

---

▶️ Quick start

cd codextui
.venv/bin/codextui

By default, codextui opens a startup mode selector:

• 1 → 💬 CLI shell
• 2 → 🧭 Dashboard TUI
• 3 → ⚙️ Daemon service

You can also launch a mode directly:

.venv/bin/codextui --mode cli
.venv/bin/codextui --mode tui
.venv/bin/codextui --mode daemon

You may also set a custom local data directory:

export CODEXTUI_DATA_DIR=~/.codextui
.venv/bin/codextui --data-dir ~/.codextui

---

🧠 Runtime modes

💬 CLI shell

The CLI shell is the pure terminal command mode. It does not use the full-screen Textual dashboard and is designed for users who prefer a coding-tool style workflow.

✨ Features

• 🕘 command history
• ⚡ /-triggered command suggestions
• ✍️ prefix completion such as /he or /key up
• 🔄 stdin fallback in non-interactive pipeline scenarios

🧾 Common commands

/help
/overview
/accounts
/import /path/to/auth.json
/oauth browser
/oauth device start
/oauth device poll
/keys
/key create
/key update <id-or-name>
/settings
/settings set listen_port 8088
/exit

---

🧭 Dashboard TUI

The Dashboard TUI provides a richer full-screen workspace powered by Textual.

🪟 Interface overview

• 📁 left panel shows:

  • data directory
  • overview state
  • global logs

• 🌐 when launched with --daemon-url, the dashboard uses the daemon as backend instead of touching local data.json

• 👤 Accounts page supports:

  • single-file import
  • recursive directory import
  • browser/device OAuth launch

• 🔑 API Keys page supports an update form where:

  • blank = do not modify
  • - = clear the field

• ⚙️ Settings page can edit:

  • Auth base URL
  • OAuth redirect URI
  • callback bind host / port
  • default listen port

---

⚙️ Daemon service

The Daemon service is the long-running backend mode.

It holds the real data directory and OAuth session state, while CLI/TUI instances can behave as lightweight frontends.

▶️ Start daemon locally

cd codextui
.venv/bin/codextui --mode daemon --data-dir ~/.codextui --daemon-host 127.0.0.1 --daemon-port 8099

Then connect from another terminal:

.venv/bin/codextui --mode cli --daemon-url http://127.0.0.1:8099
.venv/bin/codextui --mode tui --daemon-url http://127.0.0.1:8099

📌 Notes

• 🗂️ daemon owns the real storage and OAuth state
• 🔌 CLI/TUI clients can be opened or closed freely
• 📤 even if the daemon runs inside Docker, commands like /import /path/to/auth.json still work, because the client uploads file contents to the daemon rather than asking the container to read host paths directly

---

🐳 Docker deployment

To run codextui as a long-lived Docker service:

cd codextui
docker compose up -d --build

📡 Default exposed resources

• 🌐 daemon API: http://127.0.0.1:8099
• 🔐 OAuth callback mapping: 1455:1455
• 💾 persistent storage directory: ./docker-data

Host-side CLI/TUI can connect using:

.venv/bin/codextui --mode cli --daemon-url http://127.0.0.1:8099
.venv/bin/codextui --mode tui --daemon-url http://127.0.0.1:8099

🔐 OAuth note for Docker mode

If browser OAuth is used in Docker mode, keep the callback port mapping enabled because the redirect target is:

http://localhost:1455/auth/callback

If host port 1455 is already occupied, remap it like this:

cd codextui
CODEXTUI_OAUTH_REDIRECT_PORT=2455 docker compose up -d --build

This compose setup will automatically:

• 🔁 map host 2455 → container 1455
• 📝 override daemon oauth_redirect_uri to http://localhost:2455/auth/callback
• 🌍 keep the container listener on 0.0.0.0:1455

---

📚 Usage summary

👤 Account management

Import, pause, resume, and delete account records.

🔐 OAuth workflows

Support both browser-based and device-based authorization flows, including callback handling and polling.

🔑 API key management

Provide full lifecycle control for local API keys, including reset and enable/disable operations.

⚙️ Settings management

Configure listener ports, callback addresses, model defaults, import strategies, and related runtime parameters.

---

🧪 Validation

The following checks have already been performed locally:

python3 -m compileall src

• ✅ installed dependencies in local .venv with pip install -e .
• ✅ import check:

from codextui.app import CodexTuiApp

• ✅ Textual mount check:

CodexTuiApp(...).run_test()

• ✅ entrypoint check:

.venv/bin/codextui --help

• ✅ CLI mode check:

.venv/bin/codextui --mode cli

• ✅ daemon health check: GET /v1/health
• ✅ remote CLI connection check:

.venv/bin/codextui --mode cli --daemon-url http://127.0.0.1:8099

---

🎯 Current scope

codextui is already a usable standalone application for:

• 💾 local persistence
• 👤 account import and lifecycle management
• 🔐 OAuth flows
• 🔑 API key operations
• ⚙️ daemon runtime
• 🐳 Docker deployment
• 🖥️ remote CLI/TUI client connections

At the current stage, the main focus remains:

account management + OAuth + API key operations + local state control

The full local OpenAI-compatible proxy server has not yet been completely migrated into this project.

---

🧭 Design direction

This split is intentional.

By building the control plane first, codextui gets:

• 🧱 a cleaner standalone foundation
• 🧠 independent local runtime control
• 🔓 freedom from codex-lb coupling
• ♻️ reusable account import and key management workflows
• 🚀 a better path toward future local API server integration

In other words, codextui is being shaped as the workspace and control layer first, with proxy/service expansion ready to be added later.

---

🛣️ Roadmap

Possible next directions include:

• 🌐 local OpenAI-compatible API server integration
• ⚙️ deeper daemon orchestration
• 🔀 richer account scheduling / routing strategies
• 📊 better observability panels in TUI
• 🐳 stronger Docker-native workflows
• 🤖 broader terminal automation support

---

🤝 Positioning

codextui is not just a thin wrapper around older tooling.

It is intended to become a standalone local operations surface for:

• account control
• OAuth handling
• API key lifecycle
• terminal-native management workflows
• future local service orchestration

That is why the current implementation prioritizes a solid local foundation before moving further into proxy/server expansion.