CyborgShell - Proxy Configuration Guide

Overview

CyborgShell includes a lightweight CORS proxy (index.php) that enables browser-based applications to make API calls to services that don't support direct CORS requests. The proxy is optional - some AI providers work without it.

When the Proxy is Needed

Proxy Configuration Settings

Provider-Specific Settings

{
  // Claude Configuration
  "claude-proxy": "proxy/index.php?url=",
  "claude-jsonbearer": "Y",
  
  // OpenAI Configuration
  "openai-proxy": "proxy/index.php?url=",
  "openai-jsonbearer": "Y",
  
  // Gemini (no proxy needed)
  "gemini-jsonbearer": "N",
  
  // Ollama (no proxy needed)
  "ollama-jsonbearer": "N"
}

Configuration Parameters

Proxy Options

Option 1: Use the Public Proxy (Default)

The default configuration uses the public CORS proxy at cyborgshell.com/proxy/:

{
  "claude-proxy": "proxy/index.php?url=",
  "openai-proxy": "proxy/index.php?url="
}

Option 2: Self-Host the Proxy (Recommended for Production)

For complete privacy and control, host your own proxy:

1. Deploy the Proxy

Copy index.php from the CyborgShell repository to your web server:

# Example for Apache/PHP server
cp index.php /var/www/html/cors-proxy/

2. Update Configuration

Point to your proxy URL:

{
  "claude-proxy": "https://your-domain.com/cors-proxy/index.php?url=",
  "openai-proxy": "https://your-domain.com/cors-proxy/index.php?url="
}

3. Configure Proxy Security (Edit index.php)

// Whitelist your domains (source)
$arrSourceWhitelist = array('yourdomain.com', 'localhost');

// Optional: Whitelist AI provider destinations
$arrDestinationWhitelist = array(
    'api.anthropic.com', 
    'api.openai.com'
);

// Enable logging for debugging
DEFINE('LOG_OUTPUT', 'TRUE');
DEFINE('FILE_ERRORLOG', '/var/log/cors-proxy.log');

Option 3: No Proxy (Air-Gapped / Gemini-Only)

If you only use Gemini and/or Ollama, disable all proxies:

{
  "gemini-apikey": "your-key-here",
  "gemini-jsonbearer": "N",
  
  "ollama-endpoint": "http://localhost:11434/v1/chat/completions",
  "ollama-jsonbearer": "N"
}

How jsonbearer Works

When jsonbearer is Y (Proxy Mode)

• API key is included in the JSON request body
• Proxy extracts the key from the body
• Proxy adds it to the Authorization: Bearer header
• Modified request (without key in body) is forwarded to AI provider

Browser → {request + api_key in JSON} → Proxy 
       → {request with Authorization header} → AI Provider

When jsonbearer is N (Direct Mode)

• API key is sent directly in headers or URL
• No proxy manipulation needed
• Works for providers with CORS support (Gemini) or local services (Ollama)

Proxy Security Configuration

The proxy includes several security features (edit in index.php):

// Security Settings
DEFINE('MAXFILESIZE', 1024);        // Max response size in KB
DEFINE('MAXTIMEOUT', 120);          // Request timeout in seconds
DEFINE('SSL_VERIFYPEER', false);    // SSL verification (set true for production)
DEFINE('LOG_OUTPUT', 'FALSE');      // Enable request logging

// Source Whitelist (who can use the proxy)
$arrSourceWhitelist = array(
    'cyborgshell.com', 
    'yourdomain.com', 
    'localhost'
);

// Destination Whitelist (which APIs can be called)
$arrDestinationWhitelist = array(
    'api.anthropic.com',
    'api.openai.com'
);

Complete Examples

Example 1: Self-Hosted with Claude & OpenAI

{
  "claude-apikey": "sk-ant-api03-...",
  "claude-proxy": "https://proxy.yourcompany.com/index.php?url=",
  "claude-jsonbearer": "Y",
  
  "openai-apikey": "sk-proj-...",
  "openai-proxy": "https://proxy.yourcompany.com/index.php?url=",
  "openai-jsonbearer": "Y"
}

Example 2: Mixed (Proxy + Direct)

{
  "claude-apikey": "sk-ant-api03-...",
  "claude-proxy": "proxy/index.php?url=",
  "claude-jsonbearer": "Y",
  
  "gemini-apikey": "AIzaSy...",
  "gemini-jsonbearer": "N"  // Direct, no proxy
}

Example 3: Air-Gapped with Ollama Only

{
  "ollama-endpoint": "http://localhost:11434/v1/chat/completions",
  "ollama-jsonbearer": "N",
  "ollama-model": "llama3.2:latest"
}

Troubleshooting

Proxy Issues

Enable Proxy Logging

DEFINE('LOG_OUTPUT', 'TRUE');
DEFINE('FILE_ERRORLOG', '/var/log/cors-proxy.log');

Check logs for request details:

tail -f /var/log/cors-proxy.log

Security Best Practices

Air-Gap Deployment

For zero external data transfer: