### Install and Run Kiro Gateway

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Clone the repository, install dependencies, configure your environment variables, and start the server. The server will be available at http://localhost:8000 by default.

```bash
git clone https://github.com/Jwadow/kiro-gateway.git
cd kiro-gateway
pip install -r requirements.txt
cp .env.example .env
# Copy and edit .env with your credentials
python main.py
# Or with custom port (if 8000 is busy)
python main.py --port 9000
```

--------------------------------

### Display Environment Variables Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Shows an example of environment variables used for configuration. This file serves as a template for setting up the application's environment.

```bash
cat .env
```

--------------------------------

### Single Account Configuration Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Example JSON configuration for a single account using a local cache file.

```json
[
  {
    "type": "json",
    "path": "~/.aws/sso/cache/kiro-auth-token.json"
  }
]
```

--------------------------------

### Multiple Account Configuration Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Example JSON configuration for multiple accounts, including JSON, SQLite, and refresh token types.

```json
[
  {
    "type": "json",
    "path": "~/.aws/sso/cache/kiro-auth-token.json"
  },
  {
    "type": "sqlite",
    "path": "~/.local/share/kiro-cli/data.sqlite3"
  },
  {
    "type": "refresh_token",
    "refresh_token": "eyJhbGc...",
    "profile_arn": "arn:aws:codewhisperer:us-east-1:..."
  }
]
```

--------------------------------

### JSON Credentials File Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/docs/en/ARCHITECTURE.md

An example of the JSON format for credentials, used optionally for authentication.

```json
{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "expiresAt": "2025-01-12T23:00:00.000Z",
  "profileArn": "arn:aws:codewhisperer:us-east-1:.",
  "region": "us-east-1"
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/jwadow/kiro-gateway/blob/main/CONTRIBUTING.md

Install project dependencies using pip.

```bash
pip install -r requirements.txt
```

--------------------------------

### VPN/Proxy Configuration Examples

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Provides examples of how to configure the VPN_PROXY_URL environment variable for different proxy types, including HTTP, SOCKS5, and proxies with authentication.

```bash
VPN_PROXY_URL="http://127.0.0.1:7890"      # HTTP proxy
VPN_PROXY_URL="socks5://127.0.0.1:1080"    # SOCKS5 proxy
VPN_PROXY_URL="http://user:pass@proxy:8080" # With auth
```

--------------------------------

### Configuration Priority Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Demonstrates the priority order for server port configuration: CLI arguments, environment variables, and default values.

```bash
# CLI arguments: `python main.py --port 9000`
# Environment variables: `SERVER_PORT=9000`
# Default values: `8000`
```

--------------------------------

### Async HTTP Request Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Illustrates making an asynchronous HTTP GET request using httpx.AsyncClient. All I/O operations in the project should be asynchronous.

```python
async def fetch_models(self) -> List[str]:
    """Fetch available models from Kiro API."""
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.json()
```

--------------------------------

### Folder with Account Files Configuration Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Example JSON configuration for a folder containing multiple account files. The gateway scans the folder and adds each file as a separate account.

```json
[
  {
    "type": "json",
    "path": "C:\\MyAccs\\kiro67"
  }
]
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/jwadow/kiro-gateway/blob/main/tests/README.md

Installs main project dependencies and additional testing libraries like pytest, pytest-asyncio, and hypothesis.

```bash
pip install -r requirements.txt

pip install pytest pytest-asyncio hypothesis
```

--------------------------------

### Environment Variable Configuration Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Illustrates how to set required environment variables for configuration, such as API keys. These are typically loaded from a .env file.

```bash
# Required
PROXY_API_KEY="my-super-secret-password-123"
```

--------------------------------

### Debugging Steps

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

A guide to debugging issues by enabling debug logging, checking log files, running tests, and examining application logs.

```bash
# 1. Enable debug logging: `DEBUG_MODE="errors"` in `.env`
# 2. Check `debug_logs/` directory for request/response logs
# 3. Run tests: `pytest tests/unit/test_<module>.py -v`
# 4. Check application logs (loguru output)
```

--------------------------------

### Google-Style Docstring Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Illustrates the Google-style docstring format, including Args, Returns, and Examples sections. This format is used for documenting Python functions and methods.

```python
def normalize_model_name(name: str) -> str:
    """
    Normalize client model name to Kiro format.
    
    Transformations applied:
    1. claude-haiku-4-5 → claude-haiku-4.5 (dash to dot for minor version)
    2. claude-haiku-4-5-20251001 → claude-haiku-4.5 (strip date suffix)
    
    Args:
        name: External model name from client
    
    Returns:
        Normalized model name in Kiro format
    
    Examples:
        >>> normalize_model_name("claude-haiku-4-5-20251001")
        'claude-haiku-4.5'
    """
    pass
```

--------------------------------

### Install Kiro Gateway Dependencies

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Command to install all project dependencies from the requirements.txt file. Lists main dependencies including fastapi, uvicorn, httpx, loguru, requests, python-dotenv, tiktoken, pytest, pytest-asyncio, and hypothesis.

```bash
# Install all dependencies
pip install -r requirements.txt

# Main dependencies:
# - fastapi
# - uvicorn[standard]
# - httpx
# - loguru
# - requests
# - python-dotenv
# - tiktoken
# - pytest
# - pytest-asyncio
# - hypothesis
```

--------------------------------

### Install and Use Pytest-Asyncio

Source: https://github.com/jwadow/kiro-gateway/blob/main/tests/README.md

Install the pytest-asyncio package to enable asynchronous test execution. Remember to use the @pytest.mark.asyncio decorator for async test functions.

```bash
pip install pytest-asyncio
# Check for @pytest.mark.asyncio decorator
```

--------------------------------

### Start Server on Custom Port

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Launches the main application script on a port other than the default. Useful if the default port is already in use.

```bash
python main.py --port 9000
```

--------------------------------

### Authentication Headers

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Examples of authentication headers required for both OpenAI and Anthropic compatible API endpoints.

```bash
# OpenAI format
Authorization: Bearer {PROXY_API_KEY}

# Anthropic format
x-api-key: {PROXY_API_KEY}
```

--------------------------------

### Dockerize and Run Kiro Gateway

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Commands for building the Docker image, running the container with environment variables, using docker-compose for orchestration, viewing logs, stopping the container, rebuilding, and running with a custom .env file. Includes an example for mounting a credentials file.

```bash
# Build Docker image
docker build -t kiro-gateway .

# Run with Docker (using environment variables)
docker run -d \
  -p 8000:8000 \
  -e PROXY_API_KEY="your-secret-key" \
  -e REFRESH_TOKEN="your-refresh-token" \
  --name kiro-gateway \
  kiro-gateway

# Run with docker-compose (recommended)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop container
docker-compose down

# Rebuild after code changes
docker-compose up -d --build

# Run with custom .env file
docker-compose --env-file .env.production up -d

# Mount credentials file (Kiro IDE)
docker run -d \
  -p 8000:8000 \
  -v ~/.aws/sso/cache:/home/kiro/.aws/sso/cache:ro \
  -e KIRO_CREDS_FILE=/home/kiro/.aws/sso/cache/kiro-auth-token.json \
  -e PROXY_API_KEY="your-secret-key" \
  --name kiro-gateway \
  kiro-gateway
```

--------------------------------

### Anthropic API - With System Prompt

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Shows how to include a system prompt in the request to guide the AI's behavior.

```APIDOC
## POST /v1/messages (with system prompt)

### Description
Sends a message to the Anthropic API with a system prompt to define the AI's persona or instructions.

### Method
POST

### Endpoint
/v1/messages

### Headers
- **x-api-key** (string) - Required - Your API key.
- **anthropic-version** (string) - Required - The API version to use.
- **Content-Type** (string) - Required - Must be application/json.

### Request Body
- **model** (string) - Required - The model to use for generation.
- **max_tokens** (integer) - Required - The maximum number of tokens to generate.
- **system** (string) - Optional - A system prompt to guide the AI's behavior.
- **messages** (array) - Required - An array of message objects, where each object has a `role` and `content`.

### Request Example
```json
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "system": "You are a helpful assistant.",
  "messages": [{"role": "user", "content": "Hello!"}]
}
```

### Response
#### Success Response (200)
- **content** (array) - The generated content from the model.

#### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "Hello! I am a helpful assistant. How can I assist you today?"
    }
  ]
}
```
```

--------------------------------

### Model Name Normalization Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Shows how model names are normalized before being sent to the Kiro API. For example, 'claude-haiku-4-5-20251001' is normalized to 'claude-haiku-4.5'.

```python
# Client sends: "claude-haiku-4-5-20251001"
# Normalized to: "claude-haiku-4.5"
# Sent to Kiro: "claude-haiku-4.5"
```

--------------------------------

### Loguru Logging Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Shows basic usage of the loguru library for logging messages at different levels (INFO, WARNING, ERROR, DEBUG). Import logger from loguru for all logging activities.

```python
from loguru import logger

logger.info("Server starting...")
logger.warning("Token expiring soon")
logger.error(f"Failed to refresh token: {e}")
logger.debug(f"Request payload: {payload}")
```

--------------------------------

### Python Type Hinting Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Demonstrates the use of type hints for function arguments and return values in Python. Ensure all functions include type annotations for clarity and maintainability.

```python
def extract_text_content(content: Any) -> str:
    """Extract text from various content formats."""
    pass
```

```python
async def refresh_token(self) -> str:
    """Refresh access token."""
    pass
```

--------------------------------

### Tool Call Parsing Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Demonstrates how the Kiro API parser handles tool calls that may be returned in bracket format `[{...}]` instead of standard JSON.

```python
# Kiro returns: "[{\"name\":\"get_weather\",\"arguments\":{...}}]"
# Parser extracts: [{"name": "get_weather", "arguments": {...}}]
```

--------------------------------

### Check Port Usage (Linux/macOS)

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Lists processes using a specific port on Linux or macOS systems. Helps identify conflicts when starting a server.

```bash
lsof -i :8000
```

--------------------------------

### Request with Tool Calling to OpenAI Chat Completions

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Example of using cURL to make a request that includes tool definitions for function calling. This allows the model to interact with external tools.

```bash
curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer my-super-secret-password-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "What is the weather in London?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    }]
  }'
```

--------------------------------

### Debug Log Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/docs/en/ARCHITECTURE.md

This log entry shows the token counts for a specific request, detailing prompt tokens, completion tokens, and total tokens as reported by the Kiro API. It is useful for understanding token usage and debugging.

```text
[Usage] claude-opus-4-5: prompt_tokens=142211 (subtraction), completion_tokens=769 (tiktoken), total_tokens=142980 (API Kiro)
```

--------------------------------

### Generate Code Coverage Report with Pytest-Cov

Source: https://github.com/jwadow/kiro-gateway/blob/main/tests/README.md

Install pytest-cov to measure code coverage. Run pytest with the --cov flag and specify the report format. Open the generated HTML report to view details.

```bash
pip install pytest-cov
pytest --cov=kiro --cov-report=html
open htmlcov/index.html  # macOS/Linux
start htmlcov/index.html  # Windows
```

--------------------------------

### Anthropic API Request with System Prompt

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

This cURL example demonstrates how to include a system prompt when interacting with the Anthropic API. The 'system' field is a distinct parameter, not part of the messages array.

```bash
curl http://localhost:8000/v1/messages \
  -H "x-api-key: my-super-secret-password-123" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": "You are a helpful assistant.",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

--------------------------------

### FastAPI Error Handling Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Demonstrates error handling patterns using FastAPI's HTTPException for API-related errors and a try-except block for internal errors, logging them before raising an HTTPException.

```python
from fastapi import HTTPException

# For API errors
raise HTTPException(status_code=401, detail="Invalid API Key")
```

```python
# For internal errors with logging
try:
    result = await some_operation()
except Exception as e:
    logger.error(f"Operation failed: {e}")
    raise HTTPException(status_code=500, detail="Internal server error")
```

--------------------------------

### Run Kiro Gateway Docker Container

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Starts the Kiro Gateway in detached mode, mapping ports, mounting volumes for persistence, and setting environment variables for API keys and database files. Ensure the necessary directories exist locally.

```bash
docker run -d \
  -p 8000:8000 \
  -v ~/.local/share/kiro-cli:/home/kiro/.local/share/kiro-cli \
  -e KIRO_CLI_DB_FILE=/home/kiro/.local/share/kiro-cli/data.sqlite3 \
  -e PROXY_API_KEY="your-secret-key" \
  --name kiro-gateway \
  kiro-gateway
```

--------------------------------

### Pytest Async Test Structure

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Provides an example of an asynchronous test function using pytest-asyncio. It follows the Arrange-Act-Assert pattern and includes mocking for external dependencies.

```python
@pytest.mark.asyncio
async def test_token_refresh_success(mock_env_vars, mock_kiro_token_response):
    """
    Test successful token refresh.
    
    What it does: Verifies that KiroAuthManager correctly refreshes tokens
    Purpose: Ensure token lifecycle management works correctly
    """
    # Arrange
    auth_manager = KiroAuthManager()
    mock_response = mock_kiro_token_response(expires_in=3600)
    
    # Act
    with patch("httpx.AsyncClient.post") as mock_post:
        mock_post.return_value.json.return_value = mock_response
        token = await auth_manager.get_valid_token()
    
    # Assert
    assert token == mock_response["accessToken"]
    assert auth_manager._access_token == token
```

--------------------------------

### Thinking Block Extraction Example

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Illustrates the extraction of 'thinking' blocks from input text using a finite state machine. The content within `<thinking>` tags is separated from the main content.

```python
# Input: "Let me think...<thinking>reasoning here</thinking>The answer is..."
# Extracted thinking: "reasoning here"
# Extracted content: "Let me think...The answer is..."
```

--------------------------------

### Enable Account System Configuration

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Add this to your .env file to enable the account system. On first startup, credentials will be migrated to credentials.json.

```env
ACCOUNT_SYSTEM=true
```

--------------------------------

### Network Error Classification Examples

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Provides examples of how different httpx network errors are classified into user-friendly categories for easier debugging.

```python
# httpx.ConnectTimeout → "Connection timeout"
# httpx.ReadTimeout → "Server response timeout"
# DNS errors → "DNS resolution failed"
```

--------------------------------

### Build Kiro Gateway from Source

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Commands to build the Kiro Gateway Docker image from source and run it.

```bash
docker build -t kiro-gateway .
docker run -d -p 8000:8000 --env-file .env kiro-gateway
```

--------------------------------

### Run Tests

Source: https://github.com/jwadow/kiro-gateway/blob/main/CONTRIBUTING.md

Execute project tests with verbose output.

```bash
pytest -v
```

--------------------------------

### Initialize KiroAuthManager

Source: https://github.com/jwadow/kiro-gateway/blob/main/docs/en/ARCHITECTURE.md

Instantiate the KiroAuthManager with necessary credentials and region. This manager handles token retrieval and refresh.

```python
auth_manager = KiroAuthManager(
    refresh_token="your_token",
    region="us-east-1",
    creds_file="~/.aws/sso/cache/kiro-auth-token.json"
)
token = await auth_manager.get_access_token()
```

--------------------------------

### Clone and Configure Kiro Gateway

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Steps to clone the Kiro Gateway repository, navigate into the directory, and configure the .env file.

```bash
# 1. Clone and configure
git clone https://github.com/Jwadow/kiro-gateway.git
cd kiro-gateway
cp .env.example .env
# Edit .env with your credentials
```

--------------------------------

### Run Pytest Tests

Source: https://github.com/jwadow/kiro-gateway/blob/main/tests/README.md

Navigate to the project root and execute pytest to run all tests. Ensure pytest.ini is configured with the correct python path.

```bash
cd /path/to/kiro-gateway
pytest
```

--------------------------------

### Configure VPN/Proxy for Connection Issues

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

If you encounter DNS resolution errors, configure a VPN or proxy by setting the 'VPN_PROXY_URL' in your '.env' file. This is useful when the Q API endpoint is not publicly resolvable.

```env
VPN_PROXY_URL=http://127.0.0.1:7890
```

--------------------------------

### Python OpenAI SDK Usage for Chat Completions

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Demonstrates how to use the official OpenAI Python SDK to interact with the chat completions endpoint. Ensure the base URL and API key are correctly configured.

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="my-super-secret-password-123"  # Your PROXY_API_KEY from .env
)

response = client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

--------------------------------

### LangChain Integration for Chat Completions

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Shows how to integrate Kiro Gateway with LangChain using the ChatOpenAI wrapper. This simplifies building LLM applications.

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="my-super-secret-password-123",  # Your PROXY_API_KEY from .env
    model="claude-sonnet-4-5"
)

response = llm.invoke("Hello, how are you?")
print(response.content)
```

--------------------------------

### Environment Variables Configuration (.env file)

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Set up authentication using environment variables in a .env file. Required variables include REFRESH_TOKEN and PROXY_API_KEY. Optional variables like PROFILE_ARN and KIRO_REGION can also be set.

```env
# Required
REFRESH_TOKEN="your_kiro_refresh_token"

# Password to protect YOUR proxy server (make up any secure string)
PROXY_API_KEY="my-super-secret-password-123"

# Optional
PROFILE_ARN="arn:aws:codewhisperer:us-east-1:…"
KIRO_REGION="us-east-1"
```

--------------------------------

### Python Anthropic SDK - Streaming

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Demonstrates how to use the Python SDK to stream responses from the Anthropic API.

```APIDOC
## Python SDK - client.messages.stream

### Description
Uses the Python Anthropic SDK to stream response chunks incrementally.

### Method
`client.messages.stream()`

### Parameters
- **model** (string) - Required - The model to use for generation.
- **max_tokens** (integer) - Required - The maximum number of tokens to generate.
- **messages** (list) - Required - A list of message dictionaries, where each dictionary has a `role` and `content`.

### Request Example
```python
import anthropic

client = anthropic.Anthropic(
    api_key="my-super-secret-password-123",  # Your PROXY_API_KEY from .env
    base_url="http://localhost:8000"
)

with client.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
```

### Response
- **stream.text_stream** (generator) - A generator yielding text chunks as they are received.
```

--------------------------------

### Run All Kiro Gateway Tests

Source: https://github.com/jwadow/kiro-gateway/blob/main/tests/README.md

Executes the entire test suite for Kiro Gateway. Options include verbose output (-v), silent mode (-s) with short traceback (--tb=short), and running specific directories or files.

```bash
# Run the entire test suite
pytest

# Run with verbose output
pytest -v

# Run with verbose output and coverage
pytest -v -s --tb=short

# Run only unit tests
pytest tests/unit/ -v

# Run only integration tests
pytest tests/integration/ -v

# Run a specific file
pytest tests/unit/test_auth_manager.py -v

# Run a specific test
pytest tests/unit/test_auth_manager.py::TestKiroAuthManagerInitialization::test_initialization_stores_credentials -v
```

--------------------------------

### Core Dependencies and Imports

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Lists essential Python libraries and modules used in the Kiro Gateway project, including FastAPI, httpx, loguru, dotenv, and typing.

```python
# FastAPI
from fastapi import FastAPI, APIRouter, Depends, HTTPException, Request, Response
from fastapi.responses import JSONResponse, StreamingResponse
from fastapi.security import APIKeyHeader

# HTTP client
import httpx

# Logging
from loguru import logger

# Environment
from dotenv import load_dotenv
import os

# Type hints
from typing import Any, Dict, List, Optional, Tuple, AsyncGenerator

# Async
import asyncio
```

--------------------------------

### Run Kiro Gateway with Docker (.env File)

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Command to run Kiro Gateway as a detached Docker container using an .env file for configuration.

```bash
docker run -d -p 8000:8000 --env-file .env --name kiro-gateway ghcr.io/jwadow/kiro-gateway:latest
```

--------------------------------

### Configure HTTP Proxy for Kiro Gateway

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Add this to your .env file to configure an HTTP proxy for Kiro Gateway. Supports basic authentication.

```env
# HTTP proxy
VPN_PROXY_URL=http://127.0.0.1:7890

# With authentication (corporate proxies)
VPN_PROXY_URL=http://username:password@proxy.company.com:8080

# Without protocol (defaults to http://)
VPN_PROXY_URL=192.168.1.100:8080
```

--------------------------------

### Run Kiro Gateway with Docker (Credentials File - Linux/macOS)

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Command to run Kiro Gateway as a detached Docker container, mounting a local credentials file for configuration.

```bash
docker run -d \
  -p 8000:8000 \
  -v ~/.aws/sso/cache:/home/kiro/.aws/sso/cache:ro \
  -e KIRO_CREDS_FILE=/home/kiro/.aws/sso/cache/kiro-auth-token.json \
  -e PROXY_API_KEY="my-super-secret-password-123" \
  --name kiro-gateway \
  ghcr.io/jwadow/kiro-gateway:latest
```

--------------------------------

### Per-Request HTTP Clients for Streaming

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Illustrates the correct way to use httpx.AsyncClient for streaming requests to prevent CLOSE_WAIT leaks. Always use a new client for each streaming operation.

```python
# ✅ Correct: Per-request client for streaming
async with httpx.AsyncClient(timeout=timeout) as client:
    async with client.stream("POST", url, json=payload) as response:
        async for line in response.aiter_lines():
            yield line

# ❌ Wrong: Reusing shared client for streaming causes CLOSE_WAIT
```

--------------------------------

### Push Branch and Open PR

Source: https://github.com/jwadow/kiro-gateway/blob/main/CONTRIBUTING.md

Push your local branch to the remote repository and open a pull request.

```bash
git push origin your-branch
```

--------------------------------

### Python Anthropic SDK - Message Creation

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Shows how to use the Python SDK to create a message and retrieve a non-streaming response.

```APIDOC
## Python SDK - client.messages.create

### Description
Uses the Python Anthropic SDK to send a message and receive a complete, non-streaming response.

### Method
`client.messages.create()`

### Parameters
- **model** (string) - Required - The model to use for generation.
- **max_tokens** (integer) - Required - The maximum number of tokens to generate.
- **messages** (list) - Required - A list of message dictionaries, where each dictionary has a `role` and `content`.

### Request Example
```python
import anthropic

client = anthropic.Anthropic(
    api_key="my-super-secret-password-123",  # Your PROXY_API_KEY from .env
    base_url="http://localhost:8000"
)

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.content[0].text)
```

### Response
- **response.content[0].text** (string) - The text content of the first response part.
```

--------------------------------

### Run Kiro Gateway Server

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Commands to run the Kiro Gateway server with default or custom host and port configurations. Can also be run directly using uvicorn.

```bash
python main.py

# Custom port
python main.py --port 9000

# Custom host and port
python main.py --host 127.0.0.1 --port 9000

# Using uvicorn directly
uvicorn main:app --host 0.0.0.0 --port 8000
```

--------------------------------

### Check Port Usage (Windows)

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Identifies processes using a specific port on Windows. Useful for troubleshooting server startup issues.

```bash
netstat -ano | findstr :8000
```

--------------------------------

### Configure Debug Logging Mode

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

To enable debug logging, add the 'DEBUG_MODE' variable to your '.env' file. The 'errors' mode is recommended for troubleshooting, saving logs only for failed requests.

```env
# Debug logging mode:
# - off: disabled (default)
# - errors: save logs only for failed requests (4xx, 5xx) - recommended for troubleshooting
# - all: save logs for every request (overwrites on each request)
DEBUG_MODE=errors
```

--------------------------------

### Display Kiro Credentials File Environment Variable

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Prints the value of the KIRO_CREDS_FILE environment variable. Helps in debugging credential-related issues.

```bash
echo $KIRO_CREDS_FILE
```

--------------------------------

### Streaming Request to OpenAI Chat Completions

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Demonstrates how to make a streaming request to the chat completions endpoint using cURL. This is useful for real-time responses.

```bash
curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer my-super-secret-password-123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is 2+2?"}
    ],
    "stream": true
  }'
```

--------------------------------

### Run Kiro Gateway with Docker (Credentials File - Windows PowerShell)

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Command to run Kiro Gateway as a detached Docker container on Windows, mounting a local credentials file for configuration.

```powershell
docker run -d `
  -p 8000:8000 `
  -v ${HOME}/.aws/sso/cache:/home/kiro/.aws/sso/cache:ro `
  -e KIRO_CREDS_FILE=/home/kiro/.aws/sso/cache/kiro-auth-token.json `
  -e PROXY_API_KEY="my-super-secret-password-123" `
  --name kiro-gateway `
  ghcr.io/jwadow/kiro-gateway:latest
```

--------------------------------

### Anthropic API - Streaming

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Demonstrates how to enable streaming to receive response chunks as they are generated.

```APIDOC
## POST /v1/messages (streaming)

### Description
Enables streaming to receive response chunks incrementally as they are generated by the model.

### Method
POST

### Endpoint
/v1/messages

### Headers
- **x-api-key** (string) - Required - Your API key.
- **anthropic-version** (string) - Required - The API version to use.
- **Content-Type** (string) - Required - Must be application/json.

### Request Body
- **model** (string) - Required - The model to use for generation.
- **max_tokens** (integer) - Required - The maximum number of tokens to generate.
- **stream** (boolean) - Required - Set to `true` to enable streaming.
- **messages** (array) - Required - An array of message objects, where each object has a `role` and `content`.

### Request Example
```json
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "stream": true,
  "messages": [{"role": "user", "content": "Hello!"}]
}
```

### Response
#### Success Response (200)
- **stream** (string) - A stream of text chunks representing the model's response.

#### Response Example
```
Hello! This is a streamed response.
```
```

--------------------------------

### Run Tests for Kiro Gateway

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Commands for running tests using pytest, including options for verbose output, specific files or tests, and running only unit or integration tests. Also includes options to stop on first failure, show local variables on errors, and run with coverage.

```bash
# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/unit/test_auth_manager.py -v

# Run specific test
pytest tests/unit/test_auth_manager.py::TestKiroAuthManagerInitialization::test_initialization_stores_credentials -v

# Run only unit tests
pytest tests/unit/ -v

# Run only integration tests
pytest tests/integration/ -v

# Stop on first failure
pytest -x

# Show local variables on errors
pytest -l

# Run with coverage
pip install pytest-cov
pytest --cov=kiro --cov-report=html
```

--------------------------------

### Configuration Environment Variables

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Environment variables used to configure Kiro Gateway, including authentication credentials, region, server settings, and debug modes.

```bash
KIRO_CREDS_FILE="~/.aws/sso/cache/kiro-auth-token.json"  # JSON file
REFRESH_TOKEN="your_refresh_token"                        # Direct token
KIRO_CLI_DB_FILE="~/.local/share/kiro-cli/data.sqlite3" # SQLite DB

# Optional
PROFILE_ARN="arn:aws:codewhisperer:us-east-1:..."
KIRO_REGION="us-east-1"
SERVER_HOST="0.0.0.0"
SERVER_PORT="8000"
VPN_PROXY_URL="http://127.0.0.1:7890"  # For restricted networks

# Debug logging (off by default)
DEBUG_MODE="off"  # or "errors" or "all"
```

--------------------------------

### Run Kiro Gateway with Docker (Environment Variables)

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Command to run Kiro Gateway as a detached Docker container using environment variables for configuration.

```bash
docker run -d \
  -p 8000:8000 \
  -e PROXY_API_KEY="my-super-secret-password-123" \
  -e REFRESH_TOKEN="your_refresh_token" \
  --name kiro-gateway \
  ghcr.io/jwadow/kiro-gateway:latest
```

--------------------------------

### Bash Command for Running Pytest

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Shows common bash commands for running pytest tests, including quick checks, the full suite, and running with coverage reporting.

```bash
# Quick check
pytest tests/unit/test_<module>.py -v
```

```bash
# Full suite
pytest -v
```

```bash
# With coverage
pytest --cov=kiro --cov-report=html
```

--------------------------------

### JSON Credentials File Configuration

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Configure the path to your Kiro credentials file and set a proxy API key. This method is compatible with Kiro IDE and Enterprise accounts.

```env
KIRO_CREDS_FILE="~/.aws/sso/cache/kiro-auth-token.json"

# Password to protect YOUR proxy server (make up any secure string)
# You'll use this as api_key when connecting to your gateway
PROXY_API_KEY="my-super-secret-password-123"
```

--------------------------------

### Docker Compose Management Commands

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Common docker-compose commands for managing Kiro Gateway: viewing logs, restarting, stopping, and updating.

```bash
docker-compose logs -f      # View logs
docker-compose restart      # Restart
docker-compose down         # Stop
docker-compose pull && docker-compose up -d  # Update
```

--------------------------------

### Authentication Auto-Detection Logic

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Explains the logic for automatically detecting the authentication method based on the presence of specific credentials.

```python
# Has clientId/clientSecret → AWS SSO OIDC
# No clientId/clientSecret → Kiro Desktop Auth
```

--------------------------------

### Configure SOCKS5 Proxy for Kiro Gateway

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Add this to your .env file to configure a SOCKS5 proxy for Kiro Gateway.

```env
# SOCKS5 proxy
VPN_PROXY_URL=socks5://127.0.0.1:1080
```

--------------------------------

### Debug Logging Modes

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Details the three available modes for debug logging: 'off' (default, production), 'errors' (recommended for troubleshooting), and 'all' (for development). Logs are saved to the 'debug_logs/' directory.

```text
- `off`: Disabled (default, production)
- `errors`: Save logs only for failed requests (4xx, 5xx) - **recommended for troubleshooting**
- `all`: Save logs for every request (development)

Logs are saved to `debug_logs/` directory.
```

--------------------------------

### Kiro CLI SQLite Database Configuration

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Configure the path to the Kiro CLI SQLite database file and set a proxy API key. This method is for users who prefer to use the Kiro CLI's database directly.

```env
KIRO_CLI_DB_FILE="~/.local/share/kiro-cli/data.sqlite3"

# Password to protect YOUR proxy server
PROXY_API_KEY="my-super-secret-password-123"

# Note: PROFILE_ARN is NOT needed for AWS SSO (Builder ID and corporate accounts)
# The gateway will work without it
```

--------------------------------

### Include Gemini Router in Main Application

Source: https://github.com/jwadow/kiro-gateway/blob/main/docs/en/ARCHITECTURE.md

Integrate the routes for the new API format into the main FastAPI application by including the router. This makes the new endpoints accessible.

```python
from kiro.routes_gemini import router as gemini_router
app.include_router(gemini_router)
```

--------------------------------

### Kiro Gateway Project Structure

Source: https://github.com/jwadow/kiro-gateway/blob/main/docs/en/ARCHITECTURE.md

This outlines the directory structure of the Kiro Gateway project, showing the organization of modules for shared functionality, API layers, and tests.

```tree
kiro-gateway/
├── main.py                    # Entry point, FastAPI application creation
├── requirements.txt           # Python dependencies
├── .env.example               # Environment configuration example
│
├── kiro/              # Main package
│   ├── __init__.py            # Package exports, version
│   │
│   │   # ═══════════════════════════════════════════════════════
│   │   # SHARED LAYER - Reused by all APIs
│   │   # ═══════════════════════════════════════════════════════
│   ├── config.py              # Configuration and constants
│   ├── auth.py                # KiroAuthManager - token management
│   ├── cache.py               # ModelInfoCache - model cache
│   ├── http_client.py         # HTTP client with retry logic
│   ├── parsers.py             # AWS SSE stream parsers
│   ├── utils.py               # Helper utilities
│   ├── tokenizer.py           # Token counting (tiktoken)
│   ├── debug_logger.py        # Debug request logging
│   ├── exceptions.py          # Exception handlers
│   ├── thinking_parser.py     # Thinking blocks parser
│   │
│   │   # ═══════════════════════════════════════════════════════
│   │   # CORE LAYER - Shared core for all APIs
│   │   # ═══════════════════════════════════════════════════════
│   ├── converters_core.py     # Shared Kiro payload building logic
│   ├── streaming_core.py      # Shared Kiro stream parsing logic
│   │
│   │   # ═══════════════════════════════════════════════════════
│   │   # OPENAI API LAYER
│   │   # ═══════════════════════════════════════════════════════
│   ├── models_openai.py       # Pydantic models for OpenAI API
│   ├── converters_openai.py   # OpenAI → Kiro adapter
│   ├── routes_openai.py       # FastAPI routes for OpenAI
│   ├── streaming_openai.py    # Kiro → OpenAI SSE formatter
│   │
│   │   # ═══════════════════════════════════════════════════════
│   │   # ANTHROPIC API LAYER
│   │   # ═══════════════════════════════════════════════════════
│   ├── models_anthropic.py    # Pydantic models for Anthropic API
│   ├── converters_anthropic.py # Anthropic → Kiro adapter
│   ├── routes_anthropic.py    # FastAPI routes for Anthropic
│   └── streaming_anthropic.py # Kiro → Anthropic SSE formatter
│
├── tests/                     # Tests
│   ├── conftest.py            # Pytest fixtures
│   ├── unit/                  # Unit tests
│   └── integration/           # Integration tests
│
├── docs/                      # Documentation
│   ├── ru/                    # Russian version
│   └── en/                    # English version
│
└── debug_logs/                # Debug logs (generated when DEBUG_MODE=all or DEBUG_MODE=errors)

```

--------------------------------

### KiroHttpClient Methods

Source: https://github.com/jwadow/kiro-gateway/blob/main/docs/en/ARCHITECTURE.md

Available methods for interacting with the Kiro API via the HTTP client, including request and client management.

```APIDOC
**Methods:**
- `request_with_retry(method, url, json_data, stream)` — request with retry
- `close()` — close client

Supports async context manager (`async with`).
```

--------------------------------

### List Available Models

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Retrieves a list of all models available through the KIRO Gateway.

```APIDOC
## GET /v1/models

### Description
Lists all available models that can be used via the KIRO Gateway.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **models** (array) - A list of available model objects.
```

--------------------------------

### OpenAI SSE Streaming Format

Source: https://github.com/jwadow/kiro-gateway/blob/main/docs/en/ARCHITECTURE.md

Demonstrates the Server-Sent Events (SSE) format used for streaming responses from the OpenAI API.

```text
data: {"id":"chatcmpl-..."."object":"chat.completion.chunk",...}

data: [DONE]
```

--------------------------------

### OpenAI API Flow Diagram

Source: https://github.com/jwadow/kiro-gateway/blob/main/docs/en/ARCHITECTURE.md

Illustrates the request flow for the OpenAI API through the Kiro Gateway.

```text
OpenAI Client
     │ POST /v1/chat/completions
     ▼
routes_openai.py ──► converters_openai.py ──► converters_core.py
     │                                              │
     │                                              ▼
     │                                        Kiro Payload
     │                                              │
     ▼                                              ▼
KiroAuthManager ──────────────────────────► KiroHttpClient
                                                   │
                                                   ▼
                                              Kiro API
                                                   │
                                                   ▼
streaming_core.py ◄─────────────────────── AWS SSE Stream
     │
     ▼
streaming_openai.py
     │
     ▼
OpenAI SSE Format ──────────────────────► OpenAI Client
```

--------------------------------

### Docker Compose Volume Mounts

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Configuration for volume mounts in docker-compose.yml for Kiro IDE credentials, kiro-cli database, and debug logs.

```yaml
volumes:
  # Kiro IDE credentials (choose your OS)
  - ~/.aws/sso/cache:/home/kiro/.aws/sso/cache:ro              # Linux/macOS
  # - ${USERPROFILE}/.aws/sso/cache:/home/kiro/.aws/sso/cache:ro  # Windows
  
  # kiro-cli database (choose your OS)
  - ~/.local/share/kiro-cli:/home/kiro/.local/share/kiro-cli  # Linux/macOS
  # - ${USERPROFILE}/.local/share/kiro-cli:/home/kiro/.local/share/kiro-cli  # Windows
  
  # Debug logs (optional)
  - ./debug_logs:/app/debug_logs
```

--------------------------------

### Display Refresh Token Environment Variable

Source: https://github.com/jwadow/kiro-gateway/blob/main/AGENTS.md

Prints the value of the REFRESH_TOKEN environment variable. Useful for debugging authentication problems.

```bash
echo $REFRESH_TOKEN
```

--------------------------------

### Run Kiro Gateway with Docker Compose

Source: https://github.com/jwadow/kiro-gateway/blob/main/README.md

Command to run Kiro Gateway in detached mode using docker-compose.

```bash
# 2. Run with docker-compose
docker-compose up -d
```

--------------------------------

### Main Functions

Source: https://github.com/jwadow/kiro-gateway/blob/main/docs/en/ARCHITECTURE.md

Core functions for processing and building data structures within the Kiro Gateway.

```APIDOC
## Main Functions

| Function |
|----------| 
| `extract_text_content(content)` |
| `merge_adjacent_messages(messages)` |
| `build_kiro_history(messages, model_id)` |
| `build_kiro_payload(request_data, conversation_id, profile_arn)` |
```