ccflare 🛡️

Note: This is a fork of snipeship/ccflare with enhancements for third-party channel services support.

Track Every Request. Go Low-Level. Never Hit Rate Limits Again.

video_compressed.mp4

Why ccflare? ccflare

• 🚀 Zero Rate Limit Errors - Automatically distribute requests across multiple accounts
• 📊 Request-Level Analytics - Track latency, token usage, and costs in real-time
• 🔍 Deep Debugging - Full request/response logging and error traces
• **⚡ <10ms Overhead / <10ms ** - Minimal performance impact on your API calls API
• 💸 Free & Open Source - Run it yourself, modify it, own your infrastructure

Quick Start

Using Docker (Recommended) 🐳

# Clone and start with docker-compose
git clone https://github.com/dctx-team/ccflare
cd ccflare
docker-compose up -d

# Or use pre-built image
docker run -d \
  --name routex \
  -p 8080:8080 \
  -v routex-data:/app/data \
  dctxteam/routex:latest

# Access services
# Dashboard: http://localhost:8080/dashboard
# API: http://localhost:8080

📖 Full Docker Documentation: See DOCKER_QUICKSTART.md for detailed Docker deployment guide.

Using Bun Directly

# Clone and install
git clone https://github.com/dctx-team/ccflare
cd ccflare
bun install

# Start ccflare (TUI + Server)
bun run ccflare

# Add channels (New-API style, recommended)New-API
bun run ccflare --add-channel "Claude Official" \
 --type anthropic \
 --api-key sk-ant-xxx \
 --priority 100

# Add third-party channel
bun run ccflare --add-channel "Proxy Service" \
 --type anthropic \
 --api-key your-proxy-key \
 --base-url https://api.proxy-service.com \
 --priority 80

# Or use legacy account mode
bun run ccflare --add-account my-account --api-key sk-ant-xxx

# Configure Claude SDK
export ANTHROPIC_BASE_URL=http://localhost:8080

# Access Web Dashboard
# Visit: http://localhost:8080/dashboard
# - Add channels or accounts
# - Monitor usage and performance

🌟 Channel Management (New-API Style)New-API

ccflare now supports new-api style channel management with priority-based load balancing:

# Add a high-priority official channel
bun run ccflare --add-channel "Official" \
 --type anthropic \
 --api-key sk-ant-xxx \
 --priority 100 \
 --weight 1

# Add medium-priority proxy channels
bun run ccflare --add-channel "Proxy1" \
 --type anthropic \
 --api-key sk-ant-yyy \
 --base-url https://api.proxy1.com \
 --priority 80 \
 --weight 2

# List all channels
bun run ccflare --list-channels

# View channel details
bun run ccflare --channel-info "Official"

# Enable/disable channels
bun run ccflare --disable-channel "Proxy1"
bun run ccflare --enable-channel "Proxy1"

# Configure load balancing strategy
bun run ccflare --set-channel-strategy priority # Default
bun run ccflare --set-channel-strategy round_robin # Equal distribution
bun run ccflare --set-channel-strategy weighted # By weight
bun run ccflare --set-channel-strategy least_used # Auto-balance

# View current strategy
bun run ccflare --get-channel-strategy

Channel Features

• 🎯 Priority-based routing (1-100)1-100
• ⚖️ 4 load balancing strategies / 4
• Priority: Select highest priority first
• Round Robin: Distribute evenly
• Weighted: Random selection by weight
• Least Used: Auto-balance load
• 📊 Per-channel statistics
• 🔄 Automatic failover (up to 3 attempts)3
• ⚡ Rate limit handling (429 detection & retry-after)429
• 🌐 Custom base URLs Base URL
• 🎛️ Runtime strategy switching
• ✨ New-API standard compatible New-API
• 🔌 Third-party service support
• Proxy services and forwarding gateways
• Custom authentication headers
• Compatible with New-API ecosystem New-API

🚀 Advanced Channel Features

Intelligent Failover

# When a channel fails, ccflare automatically tries up to 3 alternative channels
#
# Priority 100 → Priority 80 → Priority 60 → Fallback to account mode

Rate Limit Protection

# Automatically detects 429 responses and marks channel as rate-limited
#
# Parses retry-after header or defaults to 60 seconds
#
# Rate-limited channels are automatically skipped
#

Real-time Strategy Switching

# Change strategy without restarting server
#
# Changes take effect immediately for new requests
#

Per-Channel Analytics

# Track for each channel:
# - Total requests
# - Success rate
# - Last used time
# - Current status (enabled/disabled/rate-limited)

Features

🤖 Supported Models

ccflare supports 32 AI models across 5 providers / ccflare 5 **32 AI **

**Anthropic Claude (8 models) / Anthropic Claude 8 **

• claude-sonnet-4-5-20250929 - Sonnet 4.5 (latest)
• claude-sonnet-4-5 - Sonnet 4.5 (short ID)
• claude-opus-4-1-20250805 - Opus 4.1
• claude-opus-4-20250514 - Opus 4
• claude-sonnet-4-20250514 - Sonnet 4
• claude-3-7-sonnet-20250219 - Sonnet 3.7
• claude-3-5-sonnet-20241022 - Sonnet 3.5 v2
• claude-3-5-haiku-20241022 - Haiku 3.5

**OpenAI (8 models including Codex) / OpenAI 8 Codex **

• gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo
• o1-preview, o1-mini
• codex-cushman-001, code-davinci-002

** AI / Zhipu AI (8 GLM models / 8 **

• glm-4-plus, glm-4-air, glm-4-airx, glm-4-flash
• glm-4-long, glm-4v-plus, glm-4v, glm-4

**Google Gemini (5 models / 5 **

• gemini-2.5-pro-exp-0115 - Gemini 2.5 Pro (latest)
• gemini-2.0-flash-exp, gemini-1.5-pro
• gemini-1.5-flash, gemini-pro

**Azure OpenAI (3 models / 3 **

• gpt-4, gpt-4-turbo, gpt-35-turbo

🎯 Intelligent Load Balancing

• **Channel-based (New-API)New-API ** - Priority and weight-based routing with auto-failover
• 4 strategies: Priority, Round Robin, Weighted, Least Used / 4
• Runtime strategy switching
• Rate limit detection and handling
• Session-based - Maintain conversation context (5hr sessions)5

📈 Real-Time Analytics

• Token usage tracking per request
• Response time monitoring
• Rate limit detection and warnings
• Cost estimation and budgeting

🛠️ Developer Tools

• Interactive TUI TUI (bun run ccflare)
• **Beautiful Web Dashboard Web ** (http://localhost:8080/dashboard)
• 🎨 Modern gradient UI with smooth animations UI
• 📊 Color-coded statistics cards
• 🌈 Smart theming (light/dark mode)
• ⚡ Real-time updates with WebSocket / WebSocket
• 🎯 Responsive design for all devices
• CLI for account management CLI
• REST API for automation REST API

🔒 Production Ready

• Multi-tier failover: Channels → Accounts → Unauthenticated → →
• Rate limit protection (429 detection & auto-skip)429
• OAuth token refresh handling / OAuth
• SQLite database for persistence / SQLite
• Configurable retry logic
• Hot-reload configuration

Documentation

Full documentation available in docs/:

• Getting Started
• Architecture
• API Reference
• Configuration
• 🐳 Docker Deployment - Quick start with Docker
• 🐳 Docker Guide - Complete Docker documentation
• Load Balancing Strategies
• Channel Management (New-API Style) ✨
• Channel Best Practices 📚
• Troubleshooting 🔧
• New-API Feature Release

Screenshots

Real-time Dashboard	Request Logs
Analytics & Usage Tracking

Requirements

• Bun >= 1.2.8 (not required for Docker deployment)
• Docker (optional but recommended for easy deployment)
• Claude API accounts (Free, Pro, or Team)
• Or third-party channel services
• Compatible with New-API style channel providers
• Support for custom API endpoints with authentication
• Works with proxy services and forwarding gateways

Troubleshooting

Quick Diagnostic

Run the diagnostic script to check your system health:

./diagnose.sh

The diagnostic script will check:

• ✅ System environment (Bun, Node.js, disk space)
• ✅ Server status and port availability
• ✅ Configuration files
• ✅ Database integrity
• ✅ Channel configuration
• ✅ Network connectivity
• ✅ Process and performance

For detailed troubleshooting, see Troubleshooting Guide.

License

MIT - See LICENSE for details

Built with ❤️ by dctx-team