🔥 codex-mobile-re

🚀 Run Codex App UI Anywhere: Linux, Windows, or Termux on Android 🚀

Codex UI in your browser. No drama. One command.

Yes, that is your Codex desktop app experience exposed over web UI. Yes, it runs cross-platform.

codex-mobile-re is a fork rebuild of codexapp (upstream: friuns2/codex-mobile, originally from pavel-voronin/codex-web-local), focused on mobile-first web UI, thread/message rendering refinements, and long-session stability. It is published on npm as codex-mobile-re and released on GitHub as cattails-lgao/codex-mobile.

 ██████╗ ██████╗ ██████╗ ███████╗██╗  ██╗██╗   ██╗██╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝╚██╗██╔╝██║   ██║██║
██║     ██║   ██║██║  ██║█████╗   ╚███╔╝ ██║   ██║██║
██║     ██║   ██║██║  ██║██╔══╝   ██╔██╗ ██║   ██║██║
╚██████╗╚██████╔╝██████╔╝███████╗██╔╝ ██╗╚██████╔╝██║
 ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═╝ ╚═════╝

🤯 What Is This?

codex-mobile-re is a lightweight bridge that gives you a browser-accessible UI for Codex app-server workflows.

You run one command. It starts a local web server. You open it from your machine, your LAN, or wherever your setup allows.

TL;DR 🧠: Codex app UI, unlocked for Linux, Windows, and Termux-powered Android setups.

⚡ Quick Start

The main event.

# 🔓 Run instantly (recommended)
npx codex-mobile-re

# 🌐 Then open in browser
# http://localhost:5900

By default, codex-mobile-re now also starts:

cloudflared tunnel --url http://localhost:<port>

It prints the tunnel URL, terminal QR code, and password together in startup output.
Use --no-tunnel to disable this behavior.

If you are using a provider or AI gateway that is already authenticated and do not want codex-mobile-re to force codex login during startup, use:

npx codex-mobile-re --no-login

Linux 🐧

node -v   # should be 18+
npx codex-mobile-re

Windows 🪟 (PowerShell)

node -v   # 18+
npx codex-mobile-re

Termux (Android) 🤖

pkg update && pkg upgrade -y
pkg install nodejs -y
npx codex-mobile-re

Android background requirements:

1. Keep codex-mobile-re running in the current Termux session (do not close it).
2. In Android settings, disable battery optimization for Termux.
3. Keep the persistent Termux notification enabled so Android is less likely to kill it.
4. Optional but recommended in Termux:

termux-wake-lock

5. Open the shown URL in your Android browser. If the app is killed, return to Termux and run npx codex-mobile-re again.

✨ Features

The payload.

• 🚀 One-command launch with npx codex-mobile-re
• 🌍 Cross-platform support for Linux, Windows, and Termux on Android
• 🖥️ Browser-first Codex UI flow on http://localhost:5900
• 🌐 LAN-friendly access from other devices on the same network
• 🧪 Remote/headless-friendly setup for server-based Codex usage
• 🔌 Works with reverse proxies and tunneling setups
• ⚡ No global install required for quick experimentation
• 🎙️ Built-in hold-to-dictate voice input with transcription to composer draft
• 🤖 Optional Telegram bot bridge: send messages to bot, forward into mapped thread, send assistant reply back to Telegram
• 💾 Project portability: export a project as a ZIP from project or thread menus, including matching Codex chat JSONL history under .codex-project/chats/
• 📦 Project import: restore exported project ZIPs from the browser via Import Project
• 🔁 Imported chats are rewritten for the destination CODEX_HOME, project path, and currently selected provider/model so they can be resumed in the new environment
• ⚙️ Project ZIP performance: exports stream ZIP bytes with response backpressure handling and skip generated/git-ignored folders; imports still buffer the selected ZIP once because the browser upload arrives as a single file

Telegram Bot Bridge (Optional)

Set these environment variables before starting codex-mobile-re:

export TELEGRAM_BOT_TOKEN="<your-telegram-bot-token>"
export TELEGRAM_ALLOWED_USER_IDS="<your-telegram-user-id>,<optional-second-id>"
export TELEGRAM_DEFAULT_CWD="$PWD" # optional, defaults to current working directory
npx codex-mobile-re

TELEGRAM_ALLOWED_USER_IDS is required for safe access. Only allowlisted Telegram user IDs can use the bridge. If no allowed user IDs are configured, incoming Telegram messages are rejected.

To find your Telegram user ID:

1. Send a message to your bot.
2. Run curl "https://api.telegram.org/bot<your-telegram-bot-token>/getUpdates".
3. Read message.from.id from the returned update payload.

Bot commands:

• /start show quick help and thread picker
• /threads list recent threads and pick one
• /newthread create and map a new Codex thread for this Telegram chat
• /thread <threadId> map current Telegram chat to an existing thread
• /current show currently connected thread for this chat
• /history show recent history for current thread
• /status show bridge/mapping status
• /whoami show your Telegram user/chat IDs and authorization state
• /help show command reference

Outgoing assistant messages are sent with Telegram parse_mode=HTML for formatting, with automatic plain-text fallback if HTML delivery fails.

🌍 What Can You Do With This?

| 🔥 Use Case | 💥 What You Get | |---|---| | 💻 Linux workstation | Run Codex UI in browser without depending on desktop shell | | 🪟 Windows machine | Launch web UI and access from Chrome/Edge quickly | | 📱 Termux on Android | Start service in Termux and control from mobile browser | | 🧪 Remote dev box | Keep Codex process on server, view UI from client device | | 🌐 LAN sharing | Open UI from another device on same network | | 🧰 Headless workflows | Keep terminal + browser split for productivity | | 🔌 Custom routing | Put behind reverse proxy/tunnel if needed | | ⚡ Fast experiments | npx run without full global setup |

🏗️ Architecture

┌─────────────────────────────┐
│  Browser (Desktop/Mobile)   │
└──────────────┬──────────────┘
               │ HTTP/WebSocket
┌──────────────▼──────────────┐
│      codex-mobile-re        │
│  (Express + Vue UI bridge)  │
└──────────────┬──────────────┘
               │ RPC/Bridge calls
┌──────────────▼──────────────┐
│      Codex App Server       │
└─────────────────────────────┘

🎯 Requirements

• ✅ Node.js 18+
• ✅ Codex app-server environment available
• ✅ Browser access to host/port
• ✅ Microphone permission (only for voice dictation)

🐛 Troubleshooting

| ❌ Problem | ✅ Fix | |---|---| | Port already in use | Run on a free port (--port <port>) or stop old process | | npx fails | Update npm/node, then retry | | Termux install fails | pkg update && pkg upgrade then reinstall nodejs | | Can’t open from other device | Check firewall, bind address, and LAN routing |

🤝 Contributing

Issues and PRs are welcome.
Bring bug reports, platform notes, and setup improvements.

⭐ Star This Repo

If you believe Codex UI should be accessible from any machine, any OS, any screen, star this project and share it. ⭐

Forked from friuns2/codex-mobile, originally from pavel-voronin/codex-web-local.