High-Performance Universal Bridge connecting Claude Code CLI & Anthropic SDKs to ANY AI Model.
Zero-crash streaming, multi-provider failover, chain-of-thought sanitization, PII redactor, and 24+ provider presets.
📌 1. Project Overview📸 2. Live Demo & Terminal Previews✨ 3. Features🛠️ 4. Tech Stack🏗️ 5. Architecture📁 6. Project Structure⚙️ 7. Installation and Setup🚀 8. Usage & User Flow🧪 9. Testing & Diagnostics🔒 10. Security & Privacy Safeguards💡 11. Engineering Decisions🔮 12. Limitations and Future Improvements🤝 13. Contributing & Code of Conduct📄 14. License
Claude Code CLI is one of the most capable agentic coding tools available today. However, it is natively locked to Anthropic's commercial cloud endpoints.
ClaudeGate is a lightweight, high-throughput, and secure local API gateway that bridges Anthropic's Messages API protocol (/v1/messages
and /v1/messages/count_tokens
) into standard OpenAI-compatible Chat Completions.
With ClaudeGate, developers can power Claude Code CLI, Cursor, and Anthropic SDK applications using:
- 🆓
Free & Frontier AI Cloud Models: Stealth Ox Alpha, OpenRouter (Claude Opus 5 / Sonnet 5 / Haiku 4.5), OpenAI (GPT-5.6 Sol / Terra / Luna), DeepSeek (V4-Pro & V4-Flash), Google Gemini (3.1 Pro / 3.7 Flash / 3.5 Flash-Lite), Alibaba Qwen (Qwen3.8-Max / Qwen3.7-Plus / Qwen3.8-27B), Moonshot Kimi (K3 2.8T & K2.7 Code), Meta (Muse Spark 1.2 & Muse Glimmer), Z.ai GLM (GLM-5.3 & GLM-5-Turbo), MiniMax (M3 & M2.7), Cohere (Command A+ / A / R7B), Mistral (Large 3 / Medium 3.5 / Small 4), Perplexity (Sonar Reasoning Pro). - 🔒
100% Private Local Offline Models: Ollama, LM Studio, vLLM (DeepSeek V4-Pro quantized, Qwen3.6-35B-A3B, Muse Glimmer - zero data leaves your machine). - 🧠
Next-Gen Model Mapping: Seamlessly routes all Claude versions (Claude 3.5, 3.7, 4.x, 4.5, 5.x, Fable, Mythos) to your configured
BIG_MODEL
,MIDDLE_MODEL
, andSMALL_MODEL
tiers or passes through direct model slugs. - 🏢 Enterprise Private Deployments: Azure OpenAI Service, AWS Amazon Q (via Kiro Bridge), Meta Muse Spark.
ClaudeGate in active operation, translating Claude Code CLI tool calls, bash commands, and streaming tokens in real-time:
- ⚡
Zero-Crash SSE Streaming: Translates raw OpenAI chunk streams into Anthropic Server-Sent Events (
content_block_start
,content_block_delta
,message_delta
,message_stop
). Mid-stream disconnects and upstream errors are caught gracefully without crashing Starlette/ASGI. - 🔄
Automatic Multi-Provider Failover: Seamlessly fails over from primary upstream to backup providers (e.g. OpenRouter$\rightarrow$ Groq$\rightarrow$ local Ollama) on transient503
,429
, or timeout errors without dropping the active client session. - 🛡️
PII & Secret Sanitizer: Intercepts outgoing prompts and automatically scrubs AWS keys, GitHub PATs, OpenAI tokens, and SSH private keys before requests leave your computer (SANITIZE_SECRETS=true
). - 🛠️
Full Bi-directional Tool / Function Calling: Seamlessly translates Claude Code file-system operations, terminal commands, and search tools into OpenAI function calls and vice versa. - 🧹
Chain-of-Thought /: Cleanses internal reasoning tokens and<thinking>
Sanitizer<thinking>
blocks from conversation history so multi-turn reasoning models (like DeepSeek R1/V4) never trigger400 Bad Request
errors on follow-up turns. - ⏳
Extended 10-Minute Keep-Alive: Tuned TCP socket lifespan (timeout_keep_alive=600
) to prevent Node.jsECONNRESET
drops during prolonged user typing s. - 🎛️
Universal CLI Tooling: Interactive setup wizard (--setup
), live connectivity diagnostic (--test
), and 24+ instant preset switches (--preset <name>
). - 🐳 Docker & Compose Ready: Run as a standalone daemon container with health-check monitoring.
Backend Framework:FastAPI(High-performance async ASGI web framework)** ASGI Server**:Uvicorn(Configured with custom socket keep-alives and signal handling)** Data Validation & Schemas**:Pydantic v2(Strict type serialization for Anthropic & OpenAI payloads)** HTTP Clients**:httpx&openai-python(Async connection pooling and streaming response parsing)Security & Crypto: Pythonhmac
(Constant-time token authentication) and Regex Token Redaction EngineContainerization: Docker & Docker Compose (Multi-stage Python slim base image)
ClaudeGate sits transparently between Claude Code CLI and your chosen AI model provider:
flowchart LR
A["Claude Code CLI\nor Anthropic SDK"] -- "POST /v1/messages\n(Anthropic Schema)" --> B["ClaudeGate Gateway\n(FastAPI / Port 8082)"]
subgraph CoreEngine ["ClaudeGate Core Engine"]
B --> C["Constant-Time Auth & IP Validator"]
C --> D["Request Sanitizer\n(PII & Credential Redaction)"]
D --> E["Protocol Converter\n(Tools, Messages, System Prompts)"]
E --> F["Upstream Client & Failover Controller"]
end
subgraph Upstream ["Upstream AI Providers"]
F -- "Primary Request" --> G["Primary Provider\n(OpenRouter / DeepSeek / Gemini)"]
F -. "Auto Failover on 503/429" .-> H["Backup Provider\n(Groq / Local Ollama)"]
end
G -- "OpenAI Chunk Stream" --> I["SSE Stream Adapter\n(Zero-Crash Generator)"]
H -- "OpenAI Chunk Stream" --> I
I -- "Anthropic SSE Events" --> A
ClaudeGate/
├── assets/ # Visual assets and screenshots
│ ├── ClaudeGate.png # Project Banner & Logo
│ ├── claude_terminal_ss.png # Claude Code CLI in action
│ └── proxy_terminal.png # ClaudeGate terminal proxy log
├── Dockerfile # Container image specification
├── docker-compose.yml # Container service configuration
├── requirements.txt # Python package dependencies
├── pyproject.toml # Modern package build configuration
├── setup.py # Legacy pip install compatibility
├── start_proxy.py # CLI & Server launcher script
├── .env.example # Comprehensive environment template
├── LICENSE # MIT License
├── SECURITY.md # Security policy & reporting guidelines
├── CODE_OF_CONDUCT.md # Community standard of conduct
├── CONTRIBUTING.md # Contribution guidelines
├── CHANGELOG.md # Version release history
├── README.md # Project documentation
│
├── presets/ # Ready-to-use provider templates
│ ├── openrouter.env # OpenRouter (Claude Opus 5, Sonnet 5, Haiku 4.5)
│ ├── groq.env # Groq (DeepSeek V4-Pro, Llama 4 Maverick, Muse Glimmer)
│ ├── ollama.env # Ollama (100% Local DeepSeek V4-Pro, Qwen3.6-35B, Muse Glimmer)
│ ├── deepseek.env # DeepSeek (DeepSeek V4-Pro & V4-Flash)
│ ├── gemini.env # Google Gemini (Gemini 3.1 Pro, 3.7 Flash & 3.5 Flash-Lite)
│ ├── openai.env # OpenAI Official (GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna)
│ ├── kimi.env # Moonshot AI (Kimi K3 2.8T Reasoning & K2.7 Code)
│ ├── qwen.env # Alibaba Qwen / DashScope (Qwen3.8-Max, Qwen3.7-Plus, Qwen3.8-27B)
│ ├── mistral.env # Mistral AI (Mistral Large 3, Mistral Medium 3.5, Mistral Small 4)
│ ├── perplexity.env # Perplexity (Sonar Reasoning Pro, Sonar Pro & Sonar)
│ ├── cohere.env # Cohere (Command A+, Command A & Command R7B)
│ ├── minimax.env # MiniMax (MiniMax M3 Frontier & MiniMax M2.7)
│ ├── meta.env # Meta AI (Muse Spark 1.2, Llama 4 Maverick, Muse Glimmer)
│ ├── zai.env # Z.ai / Zhipu GLM (GLM-5.3 Flagship, GLM-5-Turbo, GLM-4.7-Flash)
│ ├── together.env # Together AI (DeepSeek V4-Pro, DeepSeek V4-Flash, Qwen3.8-27B)
│ ├── fireworks.env # Fireworks AI (DeepSeek V4-Pro, DeepSeek V4-Flash, Qwen3.8-27B)
│ ├── cerebras.env # Cerebras (DeepSeek V4-Pro, Llama 4 Maverick, Muse Glimmer)
│ ├── sambanova.env # SambaNova Cloud (DeepSeek V4-Pro, Llama 4 Maverick, Qwen3.8-27B)
│ ├── siliconflow.env # SiliconFlow (DeepSeek V4-Pro, DeepSeek V4-Flash, Qwen3.8-27B)
│ ├── lmstudio.env # LM Studio Desktop (DeepSeek V4-Pro & Muse Glimmer)
│ ├── vllm.env # vLLM Self-Hosted GPU (DeepSeek V4-Pro & Qwen3.6-35B)
│ ├── azure.env # Azure OpenAI Service (o1 & GPT-5.6 Enterprise Deployments)
│ ├── kiro.env # AWS Amazon Q Developer / Claude Opus 5 Bridge
│ ├── ox.env # Stealth Ox Alpha (Frontier Reasoning Model)
│ └── nemotron.env # Nvidia Nemotron Free Tier
│
├── scripts/ # Verification & test utilities
│ ├── verify_failover.py # Automated failover simulation runner
│ └── test_live_nemotron_ox.py # Live dual-model probe (Nemotron & Ox Alpha)
│
└── src/ # Source code
├── main.py # FastAPI app & Uvicorn lifecycle
├── cli.py # CLI commands, setup wizard & test runner
├── api/
│ └── endpoints.py # /v1/messages, /health & /count_tokens routes
├── conversion/
│ ├── request_converter.py # Anthropic -> OpenAI message & tool parsing
│ └── response_converter.py # OpenAI stream -> Anthropic SSE translation
├── core/
│ ├── client.py # Async client with failover & retry logic
│ ├── config.py # Dynamic environment & constant-time auth
│ ├── constants.py # Anthropic & OpenAI protocol constants
│ ├── logging.py # Structured logging configuration
│ └── model_manager.py # Intelligent model tier & slug router
├── models/
│ ├── claude.py # Pydantic schemas for Anthropic API
│ └── openai.py # Pydantic schemas for OpenAI API
└── security/
└── sanitizer.py # Secret, AWS key, and PAT redaction engine
git clone https://github.com/Santosh-Prasad-Verma/ClaudeGate.git
cd ClaudeGate
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Launch the interactive configuration wizard:
python start_proxy.py --setup
Or load a ready-made preset directly:
python start_proxy.py --preset openrouter
You can configure Claude Code CLI to communicate with ClaudeGate using either Permanent or Session-Based configuration:
Edit (or create) ~/.claude/settings.json
to automatically route all future claude
commands to ClaudeGate:
{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8082",
"ANTHROPIC_API_KEY": "sk-claudegate-local"
}
}
Export the variables in your active shell before launching Claude:
export ANTHROPIC_BASE_URL="http://127.0.0.1:8082"
export ANTHROPIC_API_KEY="sk-claudegate-local"
Run the built-in diagnostic test to verify your upstream provider connection and measure latency:
python start_proxy.py --test
Expected Output:
🔍 Testing upstream connection...
Provider Base URL: https://openrouter.ai/api/v1
Test Model: stealth/ox-alpha
✅ Connection Successful! Model is active and responsive.
Status: 200 OK
You can also probe the gateway health endpoint directly from your terminal:
curl http://127.0.0.1:8082/health
Once setup is complete, your day-to-day workflow looks like this:
┌─────────────────────────────────────────────────────────────────────────────┐
│ TERMINAL 1: Start ClaudeGate Gateway Daemon │
│ $ cd ClaudeGate && python start_proxy.py │
│ [Gateway listening on http://127.0.0.1:8082 (OpenRouter/Groq/Ollama)] │
└──────────────────────────────────────┬──────────────────────────────────────┘
│ (Translates Anthropic ⟷ OpenAI protocol)
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ TERMINAL 2: Your Codebase Workspace (Run Claude Code) │
│ $ cd /path/to/my-project │
│ $ claude │
│ │
│ > "Add JWT authentication to src/auth.py and run the unit tests" │
│ │
│ Claude Code ──────► ClaudeGate (8082) ──────► DeepSeek R1 / Qwen / Groq │
│ (CLI Tool Calls) (Translates schemas) (Executes inference & tools) │
│ ◄────────────────── (Streams SSE Events) ◄──────────────────────────────── │
│ │
│ ✅ Claude Code automatically reads files, writes code, and runs bash tests! │
└─────────────────────────────────────────────────────────────────────────────┘
Start the Gateway (Terminal 1):
cd ClaudeGate
python start_proxy.py
ClaudeGate will boot up, display active model mappings, and listen onhttp://127.0.0.1:8082
. - Open Your Coding Project (Terminal 2): Navigate to whatever software project or repo you want to work on:
cd ~/my-flutter-app # or any project directory
Launch Claude Code:
claude
You can now type natural language instructions as usual. Claude Code will execute file inspections, bash commands, multi-file edits, and git commits powered entirely by your chosen backend model! - Switching Models On The Fly: Want to swap from free cloud models (OpenRouter) to 100% private offline models (Ollama)? In Terminal 1:
python start_proxy.py --preset ollama
python start_proxy.py
Claude Code in Terminal 2 will immediately begin routing through local Ollama without needing a restart.
| Command | Purpose |
|---|---|
python start_proxy.py |
|
| Start the ClaudeGate server | |
python start_proxy.py --test |
|
| Run live connectivity probe & measure upstream latency | |
python start_proxy.py --setup |
|
| Launch interactive 24-provider setup wizard | |
python start_proxy.py --preset <name> |
|
Quick-load a preset (e.g. groq , gemini , ollama , deepseek ) |
|
python start_proxy.py --help |
|
| View help and available options | |
python start_proxy.py --version |
|
| Display current release version |
If you prefer to run ClaudeGate as a background Docker container:
docker compose up -d --build
docker compose logs -f
docker ps
docker compose down
ClaudeGate includes built-in live diagnostics and automated test suites:
Test your active model and measure upstream response latency:
python start_proxy.py --test
Output:
🔍 Testing upstream connection...
Provider Base URL: https://openrouter.ai/api/v1
Test Model: stealth/ox-alpha
✅ Connection Successful! Model is active and responsive.
Status: 200 OK
Simulate an upstream outage to test automatic failover:
python scripts/verify_failover.py
Run the full test suite covering non-streaming failover, SSE streaming, and endpoint security:
pytest tests/ -v
ClaudeGate implements defense-in-depth privacy controls to ensure secure self-hosting:
Localhost-Only Default (: Restricts incoming traffic exclusively to the local machine.127.0.0.1
)Constant-Time Authentication: Uses Python'shmac.compare_digest
to validatex-api-key
headers, preventing side-channel timing analysis.Secret & PII Redaction Engine: WhenSANITIZE_SECRETS="true"
, prompts are automatically scrubbed for sensitive tokens (GitHub PATs, AWS Access Keys, OpenAI Keys, Private SSH keys) before reaching upstream providers.Vulnerability Reporting: For responsible disclosure, please refer to ourSecurity Policy.
Error Markers over Generator Exceptions:Problem: In Starlette / FastAPI, raisingHTTPException
inside an activeStreamingResponse
async generator after HTTP headers (200 OK
) are flushed causes a fatalRuntimeError: response already started
and terminates the ASGI worker.Decision: ClaudeGate's generator yields formattedERROR::<status>::<message>
tokens that the SSE converter catches and translates into standard Anthropic error events, keeping the worker process healthy.
Multi-Turn:<thinking>
CleansingProblem: Reasoning models (like DeepSeek R1) output reasoning tokens. When Claude Code sends subsequent conversation turns containing these blocks in history, standard OpenAI endpoints reject the payload with400 Bad Request
.Decision: Therequest_converter
automatically identifies and filtersthinking
andredacted_thinking
content blocks before dispatching to upstream providers.
Constant-Time Client Authentication:Problem: Standard string comparisons (key == expected
) are susceptible to side-channel timing attacks.Decision: Implementedhmac.compare_digest
across all header validation points.
10-Minute TCP Keep-Alive (:timeout_keep_alive=600
)Problem: Node.js HTTP agents in Claude Code CLI drop connections withECONNRESET
if an interactive user takes longer than 5 seconds between prompts.Decision: Configured explicit keep-alive headers and Uvicorn socket timeouts to support extended interactive developer s.
Image Input Format: Multimodal image support currently converts Base64 images directly; URLs require public accessibility.** Provider-Specific Parameters**: Non-standard hyperparameters outside temperature and top_p are passed as standard OpenAI extensions.
Real-Time Web Dashboard: Built-in visual UI (http://127.0.0.1:8082/dashboard
) for live latency charts, token velocity, and cost tracking. -
Prompt Cache & SQLite Deduplication: In-memory and SQLite KV caching for repetitive codebase index prompts. -
Dynamic Complexity Router: Automatic classification of task difficulty (e.g. routing simple edits to Groq and complex architectural refactors to DeepSeek R1). -
Unix Domain Sockets (UDS): Zero-network communication option over/run/user/$UID/claudegate.sock
.
We welcome bug fixes, documentation improvements, new provider presets, and feature additions!
Contributing Guide: Check outCONTRIBUTING.mdfor local environment setup and PR workflows.Code of Conduct: This project follows theContributor Covenant v2.1.** Adding Presets**: To contribute a new preset, addpresets/<provider_name>.env
and submit a pull request!
Distributed under the MIT License. See LICENSE for more information.
Built with ❤️ for the open-source & AI developer community.
Empowering developers to run Claude Code with any model, anywhere, completely unrestricted.
⭐ If you find ClaudeGate useful, consider giving it a star on GitHub! ⭐