HF_SPACES_DEPLOYMENT.md

# HF Spaces Deployment - Claude Multi-API Key Feature

## Overview
This version of CLIProxyAPI includes support for multiple Claude API keys with round-robin load balancing, accessible through both the Management UI and API endpoints.

## What's New

### 1. Multiple Claude API Keys
- Add multiple API keys per Claude configuration
- Each key can have its own proxy URL
- Automatic round-robin load balancing across all keys
- Backward compatible with single-key configurations

### 2. Updated Management UI
The management UI (`/management.html`) now includes:
- **AI Providers** → **Claude API Configuration** section
- Add/remove multiple API keys with individual proxy settings
- Visual interface for managing key entries

### 3. API Endpoints
The following endpoints support the new `api-key-entries` field:

- `GET /api/config/claude-api-key` - Returns configurations with `api-key-entries`
- `PUT /api/config/claude-api-key` - Create/update with multiple keys
- `PATCH /api/config/claude-api-key` - Update specific fields including `api-key-entries`
- `DELETE /api/config/claude-api-key` - Delete by API key or index

## Configuration Examples

### Via Management UI
1. Access `https://your-space.hf.space/management.html`
2. Navigate to **AI Providers** → **Claude API Configuration**
3. Click **Add Configuration**
4. Add multiple API keys in the **API Keys** section
5. Save

### Via Config File (config.yaml)

```yaml
claude-api-key:
  - api-key-entries:
      - api-key: "sk-ant-api03-key1..."
        proxy-url: "http://proxy1:8080"
      - api-key: "sk-ant-api03-key2..."
        proxy-url: "http://proxy2:8080"
      - api-key: "sk-ant-api03-key3..."
    base-url: "https://api.anthropic.com"
    priority: 10
    prefix: "team-a/"
    models:
      - name: claude-3-5-sonnet-20241022
        alias: claude-sonnet
      - name: claude-3-opus-20240229
        alias: claude-opus
```

### Via API

```bash
# Add Claude configuration with multiple keys
curl -X PUT https://your-space.hf.space/api/config/claude-api-key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '[{
    "api-key-entries": [
      {"api-key": "sk-ant-api03-key1...", "proxy-url": "http://proxy1:8080"},
      {"api-key": "sk-ant-api03-key2...", "proxy-url": "http://proxy2:8080"}
    ],
    "base-url": "https://api.anthropic.com",
    "priority": 10,
    "models": [
      {"name": "claude-3-5-sonnet-20241022", "alias": "claude-sonnet"}
    ]
  }]'
```

## How It Works

1. **Load Balancing**: Each API key becomes a separate Auth entry. The system uses round-robin selection to distribute requests across all available keys.

2. **Per-Key Proxy**: Each API key entry can specify its own `proxy-url`. If not specified, it falls back to the key-level `proxy-url` or no proxy.

3. **Backward Compatibility**: The old single `api-key` field still works. If `api-key-entries` is empty, the system uses the single `api-key`.

4. **Failover**: If one API key fails (e.g., rate limited), the system automatically tries the next key in the rotation.

## Files Modified

### Backend (Go)
- `internal/config/config.go` - Added `ClaudeAPIKeyEntry` type and updated `ClaudeKey`
- `internal/watcher/synthesizer/config.go` - Updated `synthesizeClaudeKeys()` for multi-key support
- `internal/watcher/diff/config_diff.go` - Added diff detection for `api-key-entries`
- `internal/api/handlers/management/config_lists.go` - Updated API handlers
- `internal/managementasset/management.html` - Updated React UI build

### Frontend (React/TypeScript)
- `management-center/src/types/provider.ts` - Added `apiKeyEntries` to types
- `management-center/src/components/providers/ClaudeSection/ClaudeModal.tsx` - New multi-key UI
- `management-center/src/components/providers/types.ts` - Updated form state types
- `management-center/src/i18n/locales/*.json` - Added translation keys

## Testing

All tests pass for the modified components:
```bash
go test ./internal/config/... ./internal/watcher/... ./internal/api/handlers/management/... -v
```

## Deployment Notes

1. The `management.html` file is embedded in the binary at `/home/internal/managementasset/management.html`
2. The Dockerfile copies the entire project, so the management UI is included automatically
3. No additional environment variables are required for the multi-key feature
4. The feature works out of the box once deployed

## Troubleshooting

### Management UI Not Loading
- Ensure the `management.html` file exists in the Docker image
- Check that `RemoteManagement.DisableControlPanel` is not set to `true` in config

### API Keys Not Rotating
- Verify that `api-key-entries` is properly formatted in the config
- Check logs for any synthesis errors
- Ensure at least one API key has a non-empty value

### Per-Key Proxy Not Working
- Verify the proxy URL format (e.g., `http://proxy.example.com:8080`)
- Check that the proxy is accessible from the HF Spaces environment