CCProxy is a reverse proxy to api.anthropic.com/v1/messages that leverages your current Claude subscription. This server uses the official claude-code-sdk to process requests locally, allowing you to access Claude AI through standard API interfaces without separate API costs.
- Use Your Existing Subscription: Leverage your Claude Pro or Team subscription instead of paying for API access
- OAuth2 Authentication: Uses your existing Claude account authentication
- Local Execution: Runs securely on your computer
- Docker Isolation: Optional Docker support for isolated Claude Code execution
- Dual API Compatibility: Full support for both Anthropic and OpenAI API formats
- Existing Tool Integration: Drop-in replacement for applications expecting OpenAI or Anthropic APIs
- Streaming Support: Real-time response streaming for both API formats
- Local Development: Perfect for personal projects and local development
This proxy server provides two main access modes:
- Uses the official claude-code-sdk for request processing
- Advantages: Access to all tools configured in Claude Code
- Limitations: Cannot directly use ToolCall, limited model settings management
- Direct reverse proxy to api.anthropic.com with header injection
- Advantages: Full access to all API features and model settings
- Method: Only injects necessary authentication headers and OAuth token
Both modes leverage your existing Claude subscription without requiring separate API costs.
- Reverse Proxy Architecture: Routes requests to api.anthropic.com/v1/messages
- Claude OAuth2 Integration: Uses your Claude account authentication
- Dual API Compatibility: Supports both Anthropic and OpenAI API formats
- Request Translation: Seamless format conversion between API types
- Streaming Support: Real-time response streaming
- Two Access Modes: Claude Code (with tools) or API (direct access)
- Local Execution: All processing happens on your computer
- No API Keys Required: Uses your existing Claude subscription via OAuth2
- Secure Authentication: Leverages Claude's official authentication system
- Optional API Authentication: Bearer token protection for API endpoints
# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code
# Install ccproxy
pipx install git+https://github.com/caddyglow/claude-code-proxy-api.git@dev
# Optional: Enable shell completion
eval "$(ccproxy --show-completion zsh)" # For zsh
eval "$(ccproxy --show-completion bash)" # For bash# Authenticate Claude Code CLI
claude /login
# For API/raw mode (uses Anthropic OAuth2)
ccproxy auth login# Start the proxy server
ccproxy
# Use with your favorite tools
export ANTHROPIC_API_KEY=dummy
export ANTHROPIC_BASE_URL=http://127.0.0.1:8000/
aider --model claude-sonnet-4-20250514That's it! For detailed setup, see our full documentation.
Once running, you can point any application that uses OpenAI or Anthropic APIs sdk to your local proxy:
For OpenAI-compatible applications:
# Set base URL to your local proxy
export OPENAI_BASE_URL="http://localhost:8000/openai/"
export OPENAI_API_KEY="dummy-key" # Required by client libraries but not usedFor Anthropic-compatible applications:
# Set base URL to your local proxy
export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_API_KEY="dummy-key" # Required by client libraries but not usedThe proxy provides two main access modes:
| Mode | URL Prefix | Description | Use Case |
|---|---|---|---|
| Claude Code | / or /cc/ |
Uses claude-code-sdk with all tools | When you need Claude Code features |
| API | /api/ |
Direct proxy with header injection | When you need full API control |
All mode provide a compatibility interface with openai under openai like /cc/openai
Messages (Claude Code mode):
POST /v1/messages # Default route
POST /cc/v1/messages # Explicit Claude Code routeMessages (API mode - direct proxy):
POST /api/v1/messagesExample request:
{
"model": "claude-3-5-sonnet-20241022",
"messages": [
{
"role": "user",
"content": "Hello, how are you?"
}
],
"max_tokens": 1000
}Chat Completions (Claude Code mode):
POST /openai/v1/chat/completions # Default route
POST /cc/openai/v1/chat/completions # Explicit Claude Code routeChat Completions (API mode - direct proxy):
POST /api/openai/v1/chat/completionsUses OpenAI format with automatic translation to Claude format.
Health Check:
GET /healthAvailable Models:
GET /v1/models
GET /openai/v1/modelsIt supports all Claude models available to your subscription:
| Model | Description |
|---|---|
claude-opus-4-20250514 |
Claude 4 Opus (most capable) |
claude-sonnet-4-20250514 |
Claude 4 Sonnet (latest, recommended) |
claude-3-7-sonnet-20250219 |
Claude 3.7 Sonnet (enhanced) |
claude-3-5-sonnet-20241022 |
Claude 3.5 Sonnet (stable) |
claude-3-5-sonnet-20240620 |
Claude 3.5 Sonnet (legacy) |
Available models depend on your Claude subscription level.
| Variable | Description | Default |
|---|---|---|
PORT |
Local server port | 8000 |
HOST |
Server host (keep as localhost for security) | 127.0.0.1 |
LOG_LEVEL |
Logging level | INFO |
AUTH_TOKEN |
Bearer token for API authentication (optional) | None |
All the settings can be override using environment variable
CCProxy uses two separate authentication systems:
# Authenticate Claude CLI (for Claude Code mode)
claude /login
claude /status- Credentials stored at:
~/.claude/credentials.jsonor~/.config/claude/credentials.json - Managed by Claude CLI directly
# Initial login (opens browser for Anthropic OAuth2)
ccproxy auth login
# Validate credentials
ccproxy auth validate
# View credential details (auto-renews if expired)
ccproxy auth info- Credentials stored in system keyring (secure)
- Fallback to:
~/.config/ccproxy/credentials.json - Tokens are automatically renewed when using
ccproxy auth info - Works with all Claude subscription types (Pro, Team, Enterprise)
For added security, you can enable token authentication for your local API access. The proxy supports multiple authentication header formats, allowing you to use the standard Anthropic and OpenAI libraries without modification.
The proxy accepts authentication tokens in multiple formats to ensure compatibility with official client libraries:
- Anthropic SDK: Uses
x-api-keyheader by default - OpenAI SDK: Uses
Authorization: Bearerheader by default
This means you can secure your proxy instance while still using the standard libraries exactly as documented.
- Anthropic Format:
x-api-key: <token>(takes precedence) - OpenAI/Bearer Format:
Authorization: Bearer <token>
All formats use the same configured token value.
# Generate a secure token
ccproxy generate-token
# Output: AUTH_TOKEN=abc123xyz789...# Set environment variable
export AUTH_TOKEN=abc123xyz789...
# Or add to .env file
echo "AUTH_TOKEN=abc123xyz789..." >> .envWhen authentication is enabled, include the token in your API requests using any supported format:
Anthropic Format (x-api-key):
curl -H "x-api-key: abc123xyz789..." \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-4-20250514","messages":[{"role":"user","content":"Hello"}]}' \
http://localhost:8000/v1/messagesOpenAI/Bearer Format:
curl -H "Authorization: Bearer abc123xyz789..." \
-H "Content-Type: application/json" \
-d '{"model":"claude-sonnet-4-20250514","messages":[{"role":"user","content":"Hello"}]}' \
http://localhost:8000/openai/v1/chat/completionsNote: The /health endpoint remains unprotected for monitoring purposes.
## Usage Examples
(Examples are available)[exmaples/]
### curl Example
```bash
# Claude Code mode (default)
curl -X POST http://localhost:8000/v1/messages \
-H "Content-Type: application/json" \
-d '{
"model": "claude-3-5-sonnet-20241022",
"messages": [{"role": "user", "content": "Hello!"}],
}'
# API mode - direct proxy, with all the models settings
curl -X POST http://localhost:8000/api/v1/messages \
-H "Content-Type: application/json" \
-d '{
"model": "claude-3-5-sonnet-20241022",
"messages": [{"role": "user", "content": "Hello!"}],
"max_tokens": 100
}'
## Troubleshooting
### Common Issues
1. **Authentication Error**
Error: Invalid authentication credentials Solution: Ensure you're using the correct mode for your authentication method
2. **Claude Authentication**
Error: Claude not authenticated or credentials expired
Solution: Run ccproxy auth login to authenticate
Verify: Run ccproxy auth validate to check credential status
3. **API Authentication**
Error: 401 Unauthorized - Missing authentication token Solution: Include authentication token using one of:
- Anthropic format: curl -H "x-api-key: your-token" ...
- Bearer format: curl -H "Authorization: Bearer your-token" ...
4. **Port Already in Use**
Error: Port 8000 already in use Solution: Use a different port: PORT=8001 python main.py
5. **Subscription Access**
Error: Model not available Solution: Check that your Claude subscription includes the requested model
## Contributing
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Documentation
Comprehensive documentation is available:
- **[Online Documentation](https://caddyglow.github.io/claude-code-proxy-api)** - Full documentation site
- **[API Reference](https://caddyglow.github.io/claude-code-proxy-api/api-reference/overview/)** - Complete API documentation
- **[Developer Guide](https://caddyglow.github.io/claude-code-proxy-api/developer-guide/architecture/)** - Architecture and development
## Support
- Issues: [GitHub Issues](https://github.com/CaddyGlow/claude-code-proxy-api/issues)
- Documentation: [Project Documentation](https://caddyglow.github.io/claude-code-proxy-api)
## Acknowledgments
- [Anthropic](https://anthropic.com) for Claude and the Claude Code SDK
- [claude-code-sdk](https://github.com/anthropics/claude-code-sdk) for the Python SDK
- The open-source community for inspiration and contributions