OpenAI Codex CLI Termux Setup & Optimization Guide

codex_termux_setup.md

Complete Termux Setup & Optimization Guide for OpenAI Codex CLI

This guide details how to install, optimize, and maintain the official OpenAI Codex CLI (@openai/codex) inside the Termux environment on Android.

---

🛠️ The Architecture & The Challenge

Statically compiled binaries (such as Codex CLI, which is written in Rust) compiled for standard Linux:

1. Dynamic Linker Differences: Standard Linux binaries depend on glibc, whereas Android/Termux utilizes bionic libc.
2. Network/DNS Lookup Issues: Statically compiled musl binaries bypass Termux's environment DNS resolution and directly search for /etc/resolv.conf and standard root SSL store paths (like /etc/ssl/certs/ca-certificates.crt). Since these do not exist on Android's standard filesystem, all HTTPS requests (including token exchanges with https://auth.openai.com) fail with token_exchange_failed and resolution errors.

The Solution: PRoot Path Virtualization

Instead of running a heavy Linux distribution (which drains battery and CPU), we use PRoot to transparently redirect standard Linux configuration files (/etc/resolv.conf, /etc/hosts, and /etc/ssl/certs/ca-certificates.crt) to Termux's local paths. This completely satisfies the static Rust binary without overhead.

---

🚀 Step-by-Step Installation Guide

Follow these steps to perform a fresh, clean installation:

Step 1: Install Prerequisites

Ensure proot and nodejs are installed in your Termux environment:

pkg update && pkg install -y proot nodejs

Step 2: Download the Official Package

Download the latest Linux ARM64 package from NPM:

mkdir -p ~/codex-temp
cd ~/codex-temp
npm pack @openai/codex-linux-arm64@latest

Step 3: Extract and Deploy the Binary

Unpack the tarball and move the binaries to their permanent directory:

tar -xzf openai-codex-*.tgz
mkdir -p ~/.codex-cli/bin
mkdir -p ~/.codex-cli/codex-resources

# Deploy the core binary
cp package/bin/codex ~/.codex-cli/bin/codex

# Deploy the helper resources (ripgrep, bubblewrap, etc.)
cp -r package/codex-resources/* ~/.codex-cli/codex-resources/

# Set execution permissions
chmod +x ~/.codex-cli/bin/codex
chmod +x ~/.codex-cli/codex-resources/*

Step 4: Create the PRoot Wrapper Script

Create a shell wrapper at ~/bin/codex so the command is globally accessible and automatically intercepts files:

mkdir -p ~/bin
cat << 'EOF' > ~/bin/codex
#!/data/data/com.termux/files/usr/bin/bash
export PATH="/data/data/com.termux/files/home/.codex-cli/codex-resources:$PATH"
exec proot \
  -b /data/data/com.termux/files/usr/etc/resolv.conf:/etc/resolv.conf \
  -b /data/data/com.termux/files/usr/etc/hosts:/etc/hosts \
  -b /data/data/com.termux/files/usr/etc/tls/cert.pem:/etc/ssl/certs/ca-certificates.crt \
  -b /data/data/com.termux/files/usr/etc/tls/cert.pem:/etc/ssl/certs/ca-bundle.crt \
  /data/data/com.termux/files/home/.codex-cli/bin/codex "$@"
EOF

chmod +x ~/bin/codex

Step 5: Clean Up

Remove the temporary installation folder:

rm -rf ~/codex-temp

---

🔄 How to Update to New Codex Versions

When OpenAI releases a new version of the Codex CLI, you can upgrade your setup effortlessly using this automated command structure.

Version Upgrade Script

Run this script in Termux to fetch the latest version and update your existing binary:

#!/data/data/com.termux/files/usr/bin/bash
set -e

# 1. Fetch latest version number
LATEST_VER=$(npm view @openai/codex-linux-arm64 version)
echo "Found latest version: $LATEST_VER"

# 2. Setup temporary folder
TEMP_DIR=$(mktemp -d -p "$HOME")
cd "$TEMP_DIR"

# 3. Pack and extract
echo "Downloading package..."
npm pack "@openai/codex-linux-arm64@$LATEST_VER" --silent
tar -xzf openai-codex-*.tgz

# 4. Replace binary and resources
echo "Updating binaries..."
cp package/bin/codex ~/.codex-cli/bin/codex
cp -r package/codex-resources/* ~/.codex-cli/codex-resources/

# 5. Apply permissions
chmod +x ~/.codex-cli/bin/codex
chmod +x ~/.codex-cli/codex-resources/*

# 6. Cleanup
cd "$HOME"
rm -rf "$TEMP_DIR"

echo "✅ Upgrade successful! Codex CLI updated to version $LATEST_VER"
codex --version

---

🧠 Instruction Injection (AGENTS.override.md)

To inject your custom system instructions, notifications, and rules globally, you can write them directly to your Codex configuration home:

mkdir -p ~/.codex
nano ~/.codex/AGENTS.override.md

Codex will automatically merge these rules and prepend them to all agent sessions globally.

---

🔍 Troubleshooting & Common Errors

1. Connection Conflict Error (localhost but the connection is errored)

Error Message:

Error: Remote control is enabled on localhost but the connection is errored.

Cause: This error typically occurs when another instance of codex remote-control is already running in the background. Codex binds to a specific local socket port (default 1455) for remote control coordination. If an orphaned codex process from a previous or closed Termux session is still active, new launches will fail to bind.

Solution: Identify and terminate the orphaned background codex processes:

1. List all active Codex processes:

   ps -ef | grep codex

2. Kill the conflicting processes: Use the Process IDs (PIDs) shown in the list:

   kill -9 <PIDs>

3. Restart the remote control server:

   codex remote-control

2. Missing Chat History / Blank Sidebar (SQLite WAL Lockup)

Symptoms: You open the Codex app or browser remote control window, but the chat history or recent sessions list in the sidebar is completely empty ("No chats"), even though the rollout files exist under ~/.codex/sessions/.

Cause: By default, Codex configures its SQLite databases (state_5.sqlite, etc.) in WAL (Write-Ahead Logging) mode. SQLite's WAL mode relies on shared-memory files (-shm) to coordinate concurrent readers and writers. Under virtualized proot environments in Termux, POSIX shared memory mappings (mmap) often fail or get locked across the container boundary. This causes SQLite to enter a locked state, preventing the app-server from reading the session index database.

Solution (Switch to DELETE Journal Mode): Changing the SQLite databases to standard rollback mode (DELETE) forces a full database checkpoint, merges all pending transactions, permanently deletes the -wal and -shm files, and operates without shared memory mappings. This permanently bypasses the PRoot/Termux filesystem locking limitations:

1. Install SQLite CLI in Termux:

   pkg install -y sqlite

2. Ensure all background Codex processes are stopped (releasing the database locks):

   kill -9 $(pgrep -f codex) 2>/dev/null || true

3. Migrate the databases to DELETE mode: Run these three repair commands:

   sqlite3 ~/.codex/state_5.sqlite "PRAGMA journal_mode = DELETE;"
   sqlite3 ~/.codex/goals_1.sqlite "PRAGMA journal_mode = DELETE;"
   sqlite3 ~/.codex/logs_2.sqlite "PRAGMA journal_mode = DELETE;"

4. Relaunch the server:

   codex remote-control