Codex + VS Code Web (EasyPanel) Setup Guide

Overview

This repository provides a complete, production-ready guide to:

• Authenticate Codex in a remote VS Code (code-server) environment
• Fix common authentication issues
• Organize and manage projects using best practices

---

🔐 Codex Authentication (Remote Environment)

Problem

Codex uses a localhost OAuth callback (http://localhost:1455) which does not work in web-based VS Code environments.

Solution

Authenticate locally (VS Code Desktop) and copy the auth.json file to the container.

---

Step 1 — Authenticate on Desktop

1. Open VS Code Desktop
2. Install and open Codex
3. Sign in normally
4. Wait for successful authentication

---

Step 2 — Ensure auth.json exists

ls ~/.codex/auth.json

If not:

mkdir -p ~/.codex

cat > ~/.codex/config.toml <<'EOF'
cli_auth_credentials_store = "file"
EOF

Then login again.

---

Step 3 — Copy to Server

scp ~/.codex/auth.json user@SERVER_IP:/home/user/auth.json

---

Step 4 — Copy into Container

docker exec CONTAINER_NAME mkdir -p /config/.codex
docker cp /home/user/auth.json CONTAINER_NAME:/config/.codex/auth.json

---

Step 5 — Fix Permissions (CRITICAL)

docker exec CONTAINER_NAME chown abc:abc /config/.codex/auth.json
docker exec CONTAINER_NAME chmod 600 /config/.codex/auth.json

---

Step 6 — Restart Container

docker restart CONTAINER_NAME

---

Step 7 — Validate

docker exec CONTAINER_NAME ls -l /config/.codex/auth.json

Expected:

-rw------- 1 abc abc ...

---

Step 8 — Open VS Code Web

• Reload window
• Open Codex

It should be authenticated automatically.

---

🧯 Troubleshooting

Codex still not authenticated

Check:

echo $HOME

Should be:

/config

Verify:

ls /config/.codex/auth.json

---

📁 Project Structure (Best Practices)

Base Directory

/config/workspace/

---

Recommended Structure

workspace/
├── affiliates/
├── automation/
├── bots/
├── scraping/
├── experiments/

---

Create New Project

cd /config/workspace
mkdir my-project
cd my-project
code .

---

Clone GitHub Repo

cd /config/workspace
git clone https://github.com/user/repo.git
cd repo
code .

---

Private Repo

git clone https://TOKEN@github.com/user/repo.git

---

⚡ Quick Start Command

cd /config/workspace && git clone REPO_URL && cd repo && code .

---

💾 Persistence

Ensure /config is a persistent volume in EasyPanel.

Backup auth:

cp /config/.codex/auth.json /home/user/auth_backup.json

---

✅ Best Practices

• Always use /config/workspace
• One project per folder
• Use clear naming
• Version everything with Git

---

🚀 Outcome

• Fully working Codex in VS Code Web
• Persistent environment
• Scalable project structure
• Reproducible setup

---

License

Apache License 2.0