A high-performance multi-protocol AI API proxy server supporting Claude Messages API, Codex Responses API, and Gemini API with intelligent failover, multi-channel scheduling, API key rotation, and unified access.
- All-in-One Architecture: Backend integrates frontend, single container deployment, replaces Nginx
- Unified Authentication: Single key protects all endpoints (Web UI, Management API, Proxy API)
- Web Management Panel: Modern visual interface for channel management, real-time monitoring, and configuration
- Claude Messages API (
/v1/messages) - Anthropic native protocol - Codex Responses API (
/v1/responses) - OpenAI compatible protocol with session management - Gemini API (
/v1beta/models/*) - Google native protocol - Models API (
/v1/models) - Unified model list query
- ChannelKind Unified Scheduling: Three API types (Messages/Responses/Gemini) with unified scheduling architecture
- Channel Orchestration: Visual channel management, drag-and-drop priority adjustment, real-time health status
- Trace Affinity: Same user session automatically binds to the same channel for consistency
- Auto Circuit Breaker: Sliding window algorithm detects channel health, auto-breaks on high failure rate
- Failover: Automatically switches to available channels for high availability
- Multi API Keys: Each upstream can configure multiple API keys with automatic rotation
- Unified Interface: Clients only need to use Claude Messages API format
- Auto Conversion: Proxy automatically handles protocol differences between upstreams (Claude/OpenAI/Gemini)
- Plug and Play: No client code changes needed when switching upstream services
- Real-time Request Monitoring: View ongoing requests and historical logs
- Traffic Statistics: Monitor request traffic, success rate, and response latency per channel
- Dual Configuration: CLI tools and Web interface for upstream configuration
- Logging System: Complete request/response logging
- Session Management: Responses API supports multi-turn conversation tracking
# Pull and run the pre-built image
docker run -d \
--name claude-proxy \
-p 3000:3000 \
-e PROXY_ACCESS_KEY=your-super-strong-secret-key \
-v $(pwd)/.config:/app/.config \
ghcr.io/stellarlinkco/proxy-gateway:latestOr use docker-compose:
# Clone the project
git clone https://github.com/stellarlinkco/proxy-gateway
cd claude-proxy
# Edit docker-compose.yml to set PROXY_ACCESS_KEY
# Start the service
docker-compose up -dDownload pre-built binaries from Releases:
| OS | Architecture | Filename |
|---|---|---|
| Windows | x64 | claude-proxy-windows-amd64.exe |
| Windows | ARM64 | claude-proxy-windows-arm64.exe |
| macOS | Intel | claude-proxy-darwin-amd64 |
| macOS | Apple Silicon | claude-proxy-darwin-arm64 |
| Linux | x64 | claude-proxy-linux-amd64 |
| Linux | ARM64 | claude-proxy-linux-arm64 |
# Linux / macOS
chmod +x claude-proxy-*
./claude-proxy-linux-amd64
# Windows (PowerShell)
.\claude-proxy-windows-amd64.exeCreate .env file in the same directory:
PROXY_ACCESS_KEY=your-super-strong-secret-key
PORT=3000
ENABLE_WEB_UI=truegit clone https://github.com/stellarlinkco/proxy-gateway
cd claude-proxy
cp backend-go/.env.example backend-go/.env
# Edit backend-go/.env
make run # or: make dev for hot reload- Web UI: http://localhost:3000
- Messages API: http://localhost:3000/v1/messages
- Responses API: http://localhost:3000/v1/responses
- Gemini API: http://localhost:3000/v1beta/models/{model}:generateContent
- Health Check: http://localhost:3000/health
User → Backend:3000 →
├─ / → Web UI (requires key)
├─ /api/* → Management API (requires key)
├─ /v1/messages → Claude Messages API proxy (requires key)
├─ /v1/responses → Codex Responses API proxy (requires key)
├─ /v1/models → Models API (requires key)
└─ /v1beta/models/* → Gemini API proxy (requires key)
Key Benefits: Single port, unified auth, no CORS issues, low resource usage
curl -X POST http://localhost:3000/v1/messages \
-H "x-api-key: your-proxy-access-key" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-3-5-sonnet-20241022",
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Hello!"}
]
}'curl -X POST http://localhost:3000/v1/messages \
-H "x-api-key: your-proxy-access-key" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-3-5-sonnet-20241022",
"stream": true,
"max_tokens": 100,
"messages": [
{"role": "user", "content": "Count to 10"}
]
}'curl -X POST http://localhost:3000/v1/responses \
-H "x-api-key: your-proxy-access-key" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"max_tokens": 100,
"input": "Hello! Please introduce yourself."
}'curl -X POST "http://localhost:3000/v1beta/models/gemini-2.0-flash:generateContent" \
-H "x-api-key: your-proxy-access-key" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"role": "user", "parts": [{"text": "Hello!"}]}
]
}'| Variable | Default | Description |
|---|---|---|
PROXY_ACCESS_KEY |
- | Required Access key for authentication |
PORT |
3000 | Server port |
ENV |
production | Environment (development/production) |
ENABLE_WEB_UI |
true | Enable web management UI |
LOG_LEVEL |
info | Log level (debug/info/warn/error) |
See ENVIRONMENT.md for full configuration options.
All endpoints (except /health) are protected by PROXY_ACCESS_KEY:
- Web UI (
/) - Key via query param or localStorage - Management API (
/api/*) -x-api-keyheader required - Proxy API (
/v1/*) -x-api-keyheader required - Health Check (
/health) - Public access
# Generate strong key
PROXY_ACCESS_KEY=$(openssl rand -base64 32)
# Production settings
ENV=production
ENABLE_REQUEST_LOGS=false
ENABLE_RESPONSE_LOGS=false
LOG_LEVEL=warnGitHub Actions workflows:
| Workflow | Description |
|---|---|
release-linux.yml |
Build Linux amd64/arm64 |
release-macos.yml |
Build macOS amd64/arm64 |
release-windows.yml |
Build Windows amd64/arm64 |
docker-build.yml |
Build multi-platform Docker images |
echo "vX.Y.Z" > VERSION
git add . && git commit -m "chore: bump version to vX.Y.Z"
git tag vX.Y.Z
git push origin main --tags- ARCHITECTURE.md - Architecture design and technical choices
- ENVIRONMENT.md - Environment variables and configuration
- DEVELOPMENT.md - Development guide and best practices
- CONTRIBUTING.md - Contribution guidelines
- CHANGELOG.md - Version history
- RELEASE.md - Release process
MIT License - see LICENSE for details.