cliproxy

CLIProxy — Check and Restart

CLIProxy is a background sidecar that proxies Anthropic-compatible API calls to GPT models via ChatGPT subscription OAuth tokens. Overdeck agents talk to it via ANTHROPIC_BASE_URL=http://127.0.0.1:8317.

Quick Status Check

# Is it running?
ss -tlnp | grep 8317

# Check PID file
cat ~/.overdeck/cliproxy/cliproxy.pid 2>/dev/null

# Verify process is alive
kill -0 $(cat ~/.overdeck/cliproxy/cliproxy.pid 2>/dev/null) 2>/dev/null && echo "alive" || echo "dead"

Restart CLIProxy

# Kill any existing instance
lsof -ti:8317 2>/dev/null | xargs -r kill 2>/dev/null || true
rm -f ~/.overdeck/cliproxy/cliproxy.pid

# Start fresh
nohup ~/.overdeck/bin/cliproxy -config ~/.overdeck/cliproxy/config.yaml \
  >> ~/.overdeck/cliproxy/cliproxy.log 2>&1 &
echo $! > ~/.overdeck/cliproxy/cliproxy.pid

# Confirm it's up (give it 2 seconds)
sleep 2 && ss -tlnp | grep 8317

Check Recent Logs

# Last 30 lines of cliproxy log
tail -30 ~/.overdeck/cliproxy/cliproxy.log

# Watch live
tail -f ~/.overdeck/cliproxy/cliproxy.log

Config and Auth

Config contents:

host: "127.0.0.1"
port: 8317
auth-dir: "~/.overdeck/cliproxy/auth"
api-keys:
  - "overdeck-local-cliproxy-key"
debug: false

Lifecycle in Overdeck

Overdeck's startCliproxy() in src/lib/cliproxy.ts handles:

1. Ensuring binary is installed
2. Writing ~/.overdeck/cliproxy/config.yaml
3. Bridging ~/.codex/auth.json → auth/codex-primary.json
4. Spawning the process detached with a PID file

CLIProxy is normally started automatically by pan up. If it crashed or was never started, use the restart snippet above.

Auth Token Refresh

If 502 errors are appearing in the log, the Codex OAuth token may be expired. CLIProxy has an auto-refresh loop, but if it fails:

# Check if auth file exists and has tokens
cat ~/.codex/auth.json | python3 -c "import sys,json; d=json.load(sys.stdin); print('access_token:', bool(d.get('tokens',{}).get('access_token')))"

# Re-bridge auth (re-runs the mapping from ~/.codex/auth.json)
# This is done automatically by pan up — or run pan install to re-authenticate

Dashboard Re-Auth Flow (PAN-913)

The Overdeck dashboard can trigger interactive Codex re-authentication when ChatGPT subscription tokens expire. This avoids requiring the user to run codex login manually in a terminal.

Flow

1. Detection — Dashboard polls GET /api/settings/codex-auth every 2 min. Status can be valid, expired, burned, missing, or unknown.
2. Initiation — User clicks Re-authenticate in Settings or the top banner. Dashboard calls POST /api/settings/codex-reauth (idempotent — returns an existing live session if one is already running).
3. Terminal login — Backend spawns a tmux session named reauth-<uuid> running codex login (or codex login --device-auth when headless), sets an HttpOnly pan_codex_reauth cookie for /ws/terminal, and the frontend opens /terminal/<sessionName> so the user can complete OAuth in a live terminal panel.
4. Polling — Frontend polls POST /api/settings/codex-reauth/status with the session name and status token every 3 s. The session is considered complete when the tmux pane exits.
5. Bridge — On completion, the backend calls bridgeCodexAuthToCliproxyAsync() to rewrite ~/.overdeck/cliproxy/auth/codex-primary.json from the fresh ~/.codex/auth.json, then returns the updated auth status.
6. Auto-retry — If an agent spawn was blocked by expired auth, the frontend automatically retries POST /api/agents once auth becomes valid.

Security

• Re-auth terminal tokens are short-lived UUIDs stored only in an HttpOnly cookie scoped to /ws/terminal; they are required for reauth-* WebSockets.
• Sessions expire from the in-memory registry after 1 hour.
• The tmux session name is a random UUID — not guessable.

API Endpoints

Manual Fallback

If the dashboard re-auth flow fails, fall back to terminal login:

# Interactive login
codex login

# Headless / device-auth flow
codex login --device-auth

# Re-bridge into cliproxy format
node -e "require('./src/lib/cliproxy.js').bridgeCodexAuthToCliproxyAsync().then(console.log)"

See Also

• src/lib/cliproxy.ts — full lifecycle implementation in Overdeck
• /pan:health — overall Overdeck health check
• /pan:up — start Overdeck (also starts cliproxy)