Configuration¶
Configure Claude Code Proxy API Server for your personal local setup and preferences.
Configuration Methods¶
The server supports multiple configuration methods with the following priority order:
- Environment Variables (highest priority)
- Configuration File (
config.json
) - Default Values (lowest priority)
Environment Variables¶
Server Configuration¶
Variable | Description | Default | Example |
---|---|---|---|
PORT |
Server port | 8000 |
PORT=8080 |
HOST |
Server host | 0.0.0.0 |
HOST=127.0.0.1 |
LOG_LEVEL |
Logging level | INFO |
LOG_LEVEL=DEBUG |
Security Configuration¶
Variable | Description | Default | Example |
---|---|---|---|
AUTH_TOKEN |
Bearer token for API authentication | None | AUTH_TOKEN=abc123xyz789... |
Claude CLI Configuration¶
Variable | Description | Default | Example |
---|---|---|---|
CLAUDE_CLI_PATH |
Path to Claude CLI | Auto-detected | CLAUDE_CLI_PATH=/usr/local/bin/claude |
Example Environment Setup¶
# .env file
PORT=8080
HOST=0.0.0.0
LOG_LEVEL=INFO
AUTH_TOKEN=abc123xyz789abcdef... # Optional authentication
CLAUDE_CLI_PATH=/opt/claude/bin/claude
Configuration File¶
Create a config.json
file in the project root for advanced configuration:
{
"server": {
"host": "0.0.0.0",
"port": 8000,
"workers": 4,
"reload": false
},
"security": {
"auth_token": "your-secure-token-here"
},
"claude": {
"cli_path": "/path/to/claude",
"default_model": "claude-3-5-sonnet-20241022",
"max_tokens": 4096,
"timeout": 30
},
"logging": {
"level": "INFO",
"format": "json",
"file": "logs/app.log"
},
"cors": {
"enabled": true,
"allow_origins": ["*"],
"allow_methods": ["GET", "POST"],
"allow_headers": ["*"]
},
"health": {
"check_claude_cli": true,
"detailed_response": false
}
}
Configuration Sections¶
Server Configuration¶
Controls the FastAPI server behavior:
{
"server": {
"host": "0.0.0.0", // Bind address
"port": 8000, // Port number
"workers": 4, // Number of worker processes
"reload": false, // Auto-reload on file changes (dev only)
"access_log": true, // Enable access logging
"proxy_headers": true // Trust proxy headers
}
}
Claude Configuration¶
Controls Claude CLI integration:
{
"claude": {
"cli_path": "/path/to/claude", // Custom CLI path
"default_model": "claude-3-5-sonnet-20241022", // Default model
"max_tokens": 4096, // Default max tokens
"timeout": 30, // Request timeout (seconds)
"auto_detect_path": true, // Auto-detect CLI path
"search_paths": [ // Custom search paths
"/usr/local/bin/claude",
"/opt/claude/bin/claude"
]
}
}
Logging Configuration¶
Controls application logging:
{
"logging": {
"level": "INFO", // Log level (DEBUG, INFO, WARNING, ERROR)
"format": "json", // Log format (json, text)
"file": "logs/app.log", // Log file path (optional)
"rotation": "1 day", // Log rotation (optional)
"retention": "30 days", // Log retention (optional)
"structured": true, // Enable structured logging
"include_request_id": true // Include request IDs
}
}
CORS Configuration¶
Configure Cross-Origin Resource Sharing:
{
"cors": {
"enabled": true, // Enable CORS
"allow_origins": ["*"], // Allowed origins
"allow_methods": ["GET", "POST"], // Allowed methods
"allow_headers": ["*"], // Allowed headers
"allow_credentials": false, // Allow credentials
"max_age": 86400 // Preflight cache duration
}
}
Security Configuration¶
Configure API authentication and security features:
{
"security": {
"auth_token": "your-secure-token-here", // Bearer token for API auth
"enabled": true, // Enable/disable auth
"token_header": "Authorization", // Header name for token
"token_prefix": "Bearer" // Token prefix
}
}
Note: When auth_token
is not set or is null, authentication is disabled.
Health Check Configuration¶
Configure health monitoring:
{
"health": {
"check_claude_cli": true, // Check Claude CLI availability
"detailed_response": false, // Include detailed health info
"timeout": 5, // Health check timeout
"include_version": true, // Include version in response
"include_metrics": false // Include basic metrics
}
}
Claude CLI Auto-Detection¶
The server automatically searches for Claude CLI in these locations:
- Environment PATH
- Common installation paths:
~/.claude/local/claude
~/node_modules/.bin/claude
./node_modules/.bin/claude
/usr/local/bin/claude
/opt/homebrew/bin/claude
/usr/bin/claude
Custom CLI Path¶
If Claude CLI is installed in a custom location:
# Environment variable
export CLAUDE_CLI_PATH=/custom/path/to/claude
# Configuration file
{
"claude": {
"cli_path": "/custom/path/to/claude"
}
}
Docker Configuration for Personal Use¶
Environment Variables¶
version: '3.8'
services:
claude-code-proxy-api:
image: claude-code-proxy
ports:
- "8000:8000"
environment:
- PORT=8000
- HOST=0.0.0.0
- LOG_LEVEL=INFO
- CLAUDE_CLI_PATH=/usr/local/bin/claude
volumes:
- ~/.config/claude:/root/.config/claude:ro
Volume Mounting for Personal Setup¶
Mount your Claude configuration and local settings:
version: '3.8'
services:
claude-code-proxy-api:
image: claude-code-proxy
ports:
- "8000:8000"
volumes:
- ./config.json:/app/config.json:ro
- ./logs:/app/logs
- ~/.config/claude:/root/.config/claude:ro
Personal Use Configuration¶
Recommended Settings for Local Development¶
{
"server": {
"host": "127.0.0.1",
"port": 8000,
"workers": 2,
"reload": true,
"access_log": true,
"proxy_headers": false
},
"logging": {
"level": "INFO",
"format": "text",
"file": "./logs/app.log",
"rotation": "1 day",
"retention": "7 days"
},
"cors": {
"enabled": true,
"allow_origins": ["http://localhost:*", "http://127.0.0.1:*"],
"allow_credentials": false
},
"health": {
"check_claude_cli": true,
"detailed_response": true
}
}
Configuration Validation¶
The server validates configuration on startup and will report errors for:
- Invalid port numbers
- Missing Claude CLI binary
- Invalid log levels
- Malformed JSON configuration
- Network binding issues
Validation Example¶
# Check configuration without starting server
uv run python -m claude_code_proxy.config.validate config.json
Personal Use Scenarios¶
Development & Testing¶
{
"server": {
"host": "127.0.0.1",
"reload": true,
"workers": 1
},
"logging": {
"level": "DEBUG",
"format": "text"
},
}
Daily Personal Use¶
{
"server": {
"host": "127.0.0.1",
"reload": false,
"workers": 2
},
"logging": {
"level": "INFO",
"format": "text"
},
}
Isolated Docker Setup¶
{
"server": {
"host": "0.0.0.0",
"reload": false,
"workers": 2
},
"logging": {
"level": "INFO",
"format": "json",
"file": "/app/logs/app.log"
},
}
Configuration Best Practices for Personal Use¶
- Use environment variables for local customization and preferences
- Use configuration files for structured settings you want to persist
- Validate configuration before starting the server
- Keep backups of your working configuration files
- Use different configurations for development vs. daily use
- Start simple - use defaults first, then customize as needed
- Secure your setup - bind to localhost (127.0.0.1) for local-only access
Troubleshooting Configuration¶
Common Issues¶
- Server won't bind to port
- Check if port is already in use:
netstat -an | grep :8000
- Try a different port:
PORT=8001
-
Check firewall settings
-
Claude CLI not found
- Verify installation:
claude --version
- Check PATH:
echo $PATH
-
Set explicit path:
CLAUDE_CLI_PATH=/path/to/claude
-
Configuration file not loaded
- Check file exists:
ls -la config.json
- Validate JSON syntax:
python -m json.tool config.json
- Check file permissions:
chmod 644 config.json
Advanced Configuration Reference¶
Complete Configuration Options¶
.env File Reference¶
# Basic server configuration
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO
WORKERS=4
RELOAD=false
# Claude configuration
CLAUDE_CLI_PATH=/usr/local/bin/claude
# Security settings
AUTH_TOKEN=your-secure-token-here
CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
# Tools handling
TOOLS_HANDLING=warning
# Security settings for subprocess execution
CLAUDE_USER=claude
CLAUDE_GROUP=claude
Complete JSON Configuration Schema¶
{
"host": "0.0.0.0",
"port": 8000,
"log_level": "INFO",
"workers": 4,
"reload": false,
"cors_origins": ["https://yourdomain.com"],
"claude_cli_path": "/usr/local/bin/claude",
"tools_handling": "warning",
"docker_settings": {
"docker_image": "claude-code-proxy:latest",
"docker_volumes": [
"$HOME/.config/claude:/data/home",
"$PWD:/data/workspace"
],
"docker_environment": {
"CLAUDE_HOME": "/data/home",
"CLAUDE_WORKSPACE": "/data/workspace"
},
"docker_additional_args": ["--network=host"],
"docker_home_directory": "/home/user/.config/claude",
"docker_workspace_directory": "/home/user/projects"
},
"claude_code_options": {
"cwd": "/path/to/working/directory",
"model": "claude-3-5-sonnet-20241022",
"max_thinking_tokens": 30000
}
}
Configuration Validation¶
All configuration values are automatically validated:
- Port: Must be between 1-65535
- Log Level: Must be DEBUG, INFO, WARNING, ERROR, or CRITICAL
- CORS Origins: Must be valid URLs or "*"
- Claude CLI Path: Must exist and be executable
- Tools Handling: Must be "error", "warning", or "ignore"
Environment-Specific Configuration Files¶
Development Environment (.env.development
)¶
HOST=127.0.0.1
PORT=8000
LOG_LEVEL=DEBUG
RELOAD=true
WORKERS=1
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
Production Environment (.env.production
)¶
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO
RELOAD=false
WORKERS=4
CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
CLAUDE_CLI_PATH=/usr/local/bin/claude
TOOLS_HANDLING=error
CLAUDE_USER=claude
CLAUDE_GROUP=claude
Advanced Configuration Patterns¶
Configuration with Environment Variable Substitution¶
{
"host": "${HOST:-0.0.0.0}",
"port": "${PORT:-8000}",
"claude_cli_path": "${CLAUDE_CLI_PATH}",
"cors_origins": ["${CORS_ORIGIN:-*}"]
}
Multi-Environment Loading Script¶
#!/bin/bash
# scripts/load-env.sh
ENV=${1:-development}
case $ENV in
"development")
export $(cat .env.development | xargs)
;;
"production")
export $(cat .env.production | xargs)
;;
*)
echo "Unknown environment: $ENV"
exit 1
;;
esac
echo "Loaded configuration for: $ENV"
CLI Configuration Commands¶
# Display current configuration
ccproxy config
# Test Claude CLI integration
ccproxy claude -- --version
# Test with Docker
ccproxy claude --docker -- --version
# Specify custom configuration file
CONFIG_FILE=/path/to/custom/config.json ccproxy run
Advanced Troubleshooting¶
Configuration Debugging¶
# Enable debug logging to see configuration loading
LOG_LEVEL=DEBUG ccproxy run
# Validate configuration without starting server
python -c "from claude_code_proxy.config.settings import get_settings; print('Config valid')"
# Check Claude CLI path resolution
ccproxy claude -- --version
Common Advanced Issues¶
-
Docker Volume Mount Issues
-
Environment Variable Substitution
-
Complex CORS Configuration