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:

# 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:

# 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:

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)