README.hf-spaces.md

# Deploying CLIProxyAPI on Hugging Face Spaces

This guide explains how to deploy CLIProxyAPI with Kiro integration on Hugging Face Spaces.

## Quick Start

1. Create a new Space on Hugging Face with "Docker" SDK
2. Set the following Secrets in your Space settings:

### Required Secrets

| Secret Name | Description |
|-------------|-------------|
| `KIRO_REFRESH_TOKEN` | Your Kiro refresh token (this is all you need!) |
| `API_KEY` | API key for authenticating requests to the proxy |

### Optional Secrets

| Secret Name | Default | Description |
|-------------|---------|-------------|
| `KIRO_REGION` | `us-east-1` | AWS region for Kiro API |
| `DEBUG` | `false` | Enable debug logging |

**Note:** `profile-arn` is automatically fetched from the token refresh API - you don't need to provide it!

## Getting Kiro Credentials

### Option 1: From Kiro Desktop App

1. Open Kiro IDE/Desktop app
2. Sign in to your account
3. Locate the credentials file (usually in `~/.kiro/` or similar)
4. Extract the `refreshToken` value

### Option 2: From kiro-cli

1. Install kiro-cli: `npm install -g @kiro/cli`
2. Login: `kiro login`
3. Find the database: `~/.local/share/kiro-cli/data.sqlite3`
4. Extract credentials using SQLite

### Option 3: Using AWS SSO

If you have AWS SSO configured for CodeWhisperer:
1. Get your SSO credentials
2. Use the AWS SSO OIDC flow for token refresh

## Dockerfile

Use `Dockerfile.hf-spaces` for HF Spaces deployment:

```bash
# Rename for HF Spaces
cp Dockerfile.hf-spaces Dockerfile
```

## Environment Variables

The startup script will automatically create a `config.yaml` from environment variables.
See `config.example.yaml` for full configuration options.

## Usage

Once deployed, use the Space URL as your API base URL:

```bash
# OpenAI-compatible endpoint
curl https://your-username-your-space.hf.space/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.5",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## Supported Models (via Kiro)

| Model ID | Description |
|----------|-------------|
| `auto` | Automatic model selection |
| `claude-sonnet-4` | Claude 4 Sonnet |
| `claude-sonnet-4.5` | Claude 4.5 Sonnet |
| `claude-haiku-4.5` | Claude 4.5 Haiku |
| `claude-opus-4.5` | Claude 4.5 Opus (may require paid tier) |
| `claude-3.7-sonnet` | Claude 3.7 Sonnet (legacy, hidden but functional) |

## Claude API Configuration with Multiple Keys

This version supports multiple Claude API keys with round-robin load balancing!

### Via Management UI

1. Access the management panel at `https://your-space.hf.space/management.html`
2. Go to **AI Providers** → **Claude API Configuration**
3. Click **Add Configuration**
4. In the **API Keys** section, add multiple keys with optional per-key proxy URLs
5. Save the configuration

### Via Config File

You can also configure multiple Claude API keys directly in your `config.yaml`:

```yaml
claude-api-key:
  - api-key-entries:
      # List your API keys and optional proxies here
      # See documentation for full syntax
    base-url: "https://api.anthropic.com"
    priority: 10
    models:
      - name: claude-3-5-sonnet-20241022
        alias: claude-sonnet
```

**Features:**
- **Round-robin load balancing**: Requests automatically rotate between all API keys
- **Per-key proxy support**: Each API key can have its own proxy configuration
- **Backward compatible**: Single `api-key` field still works
- **Automatic failover**: If one key fails, the system tries the next one

## Troubleshooting

### Token Refresh Errors
- Ensure your refresh token is valid
- Check that the profile ARN matches your account
- Verify the region is correct

### 403 Errors
- Token may have expired - restart the Space to trigger refresh
- Check if your Kiro account has access to the requested models

### Connection Issues
- If behind a firewall, you may need to configure proxy settings
- Ensure port 7860 is the exposed port (HF Spaces default)