llm-gateway/DEPLOYMENT-BRIDGES.md

OpenAI Bridge Deployment Guide

Overview

This document covers deploying the OpenAI Bridge service to Erik for ChatGPT/Codex integration.

Architecture

• openai-bridge (Port 3251): HTTP wrapper around OpenAI CLI, provides OpenAI-compatible /v1/chat/completions endpoint
• Integration: Registered in external-providers.ts as fallback provider after Ollama and Claude
• Authentication: Uses OPENAI_API_KEY environment variable (OpenAI subscription required)

Prerequisites on Erik

• OpenAI CLI tool: openai command available (homebrew: brew install openai-cli)
• Node.js 20+ installed
• PM2 process manager available
• /opt directory writable (for service deployment)
• /var/log/llm-gateway directory exists for logs

Deployment Steps

1. Automatic Setup (Recommended)

The ensure-bridges.sh script handles automatic deployment:

# Run on Erik
cd /opt/llm-gateway
bash scripts/ensure-bridges.sh

This will:

• Create /opt/openai-bridge directory if missing
• Deploy server.js and package.json
• Create logs directory

2. Manual Setup (Alternative)

If automatic script fails, deploy manually:

# On Erik
mkdir -p /opt/openai-bridge /var/log/llm-gateway

# Copy openai-bridge files from repo
cp /opt/llm-gateway/openai-bridge/server.js /opt/openai-bridge/
cp /opt/llm-gateway/openai-bridge/package.json /opt/openai-bridge/

3. Configuration

Update ecosystem.config.cjs

Edit /opt/llm-gateway/deploy/ecosystem.config.cjs:

env: {
  OPENAI_API_KEY: 'sk-proj-xxxxx...', // Your OpenAI subscription key
  OPENAI_BRIDGE_PORT: 3251,
  OPENAI_MODEL: 'gpt-4-turbo',
}

Important: Do NOT commit API keys to git. Use environment variables or .env files.

4. Deploy with PM2

# On Erik
cd /opt/llm-gateway
pm2 start deploy/ecosystem.config.cjs --update-env

This will start:

• llm-gateway (main service, port 3103)
• openai-bridge (ChatGPT bridge, port 3251)
• llm-learning (auto-learning engine)

5. Verification

# Check service status
pm2 status

# Health check
curl http://localhost:3251/health

# Sample request
curl -X POST http://localhost:3251/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4-turbo",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# View logs
pm2 logs openai-bridge

Environment Variables

Variable	Required	Default	Notes
OPENAI_API_KEY	Yes	(empty)	OpenAI subscription API key
OPENAI_BRIDGE_PORT	No	3251	Service port
OPENAI_MODEL	No	gpt-4-turbo	Default model
OPENAI_BRIDGE_URL	Yes*	http://localhost:3251	Set in ecosystem.config.cjs

*Required in gateway's environment for proper routing

Troubleshooting

Bridge Service Won't Start

# Check if openai CLI is installed
which openai
openai --version

# Install if missing (requires homebrew)
brew install openai-cli

Port 3251 Already in Use

# Find process using port
lsof -i :3251
# Kill process if needed
kill -9 <PID>

OPENAI_API_KEY Not Configured

# Check environment
pm2 show openai-bridge | grep OPENAI_API_KEY

# Update if missing
pm2 set openai-bridge OPENAI_API_KEY "sk-proj-xxxxx..."
pm2 restart openai-bridge

Health Check Fails

# Manual test of openai CLI
OPENAI_API_KEY="sk-proj-xxxxx..." openai api chat.completions.create \
  -m gpt-4-turbo \
  -g user "hello" \
  -t 0.3 \
  -M 100

Integration with LLM Gateway

Once deployed, openai-bridge is automatically:

1. Registered in provider fallback chain (after claude-bridge, cerebras, groq, etc.)
2. Used when:
   • Ollama is unavailable
   • Request specifically targets "openai" or "chatgpt" provider
   • Confidence threshold requires higher-tier reasoning
3. Monitored for:
   • Rate limits (90 requests/min)
   • Response quality and latency
   • Error rates

Rollback / Removal

# Stop openai-bridge service
pm2 stop openai-bridge
pm2 delete openai-bridge

# Remove service directory (keeps config for reinstall)
rm -rf /opt/openai-bridge

# Or keep for reinstall (without logs)
rm -rf /opt/openai-bridge/node_modules

Next Steps

1. Microsoft Copilot Integration: Similar bridge pattern once CLI available
2. Rate Limiting: Implement adaptive rate limiting per provider
3. Cost Tracking: Monitor OpenAI API usage and costs
4. Monitoring: Add Prometheus metrics for bridge health

---

Last Updated: 2026-04-25
Status: Ready for deployment