Metadata-Version: 2.4
Name: ccproxy-api
Version: 0.1.0
Summary: API server that provides an Anthropic and OpenAI compatible interface over Claude Code, allowing to use your Claude OAuth account or over the API.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: claude-code-sdk>=0.0.14
Requires-Dist: duckdb-engine>=0.17.0
Requires-Dist: duckdb>=1.1.0
Requires-Dist: fastapi[standard]>=0.115.14
Requires-Dist: httpx-sse>=0.4.1
Requires-Dist: httpx>=0.28.1
Requires-Dist: jsonschema>=0.33.2
Requires-Dist: keyring>=25.6.0
Requires-Dist: openai>=1.93.0
Requires-Dist: prometheus-client>=0.22.1
Requires-Dist: pydantic-settings>=2.4.0
Requires-Dist: pydantic>=2.8.0
Requires-Dist: rich-toolkit>=0.14.8
Requires-Dist: rich>=13.0.0
Requires-Dist: sqlmodel>=0.0.24
Requires-Dist: structlog>=25.4.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer>=0.16.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: uvicorn>=0.34.0
Description-Content-Type: text/markdown

# CCProxy API Server

`ccproxy` is a local reverse proxy server for Anthropic Claude LLM at `api.anthropic.com/v1/messages`. It allows you to use your existing Claude Max subscription to interact with the Anthropic API, bypassing the need for separate API key billing.

The server provides two primary modes of operation:
*   **SDK Mode (`/sdk`):** Routes requests through the local `claude-code-sdk`. This enables access to tools configured in your Claude environment.
*   **API Mode (`/api`):** Acts as a direct reverse proxy, injecting the necessary authentication headers. This provides full access to the underlying API features and model settings.

It includes a translation layer to support both Anthropic and OpenAI-compatible API formats for requests and responses, including streaming.

## Installation

```bash
# The official claude-code CLI is required for SDK mode
npm install -g @anthropic-ai/claude-code

# Install ccproxy
pipx install git+https://github.com/caddyglow/ccproxy-api.git@dev

# Optional: Enable shell completion
eval "$(ccproxy --show-completion zsh)"  # For zsh
eval "$(ccproxy --show-completion bash)" # For bash
```

## Authentication

The proxy uses two different authentication mechanisms depending on the mode.

1.  **Claude CLI (`sdk` mode):**
    This mode relies on the authentication handled by the `claude-code-sdk`.
    ```bash
    claude /login
    ```

2.  **ccproxy (`api` mode):**
    This mode uses its own OAuth2 flow to obtain credentials for direct API access.
    ```bash
    ccproxy auth login
    ```
    You can check the status of these credentials with `ccproxy auth validate` and `ccproxy auth info`.

## Usage

### Running the Server

```bash
# Start the proxy server
ccproxy
```
The server will start on `http://127.0.0.1:8000` by default.

### Client Configuration

Point your existing tools and applications to the local proxy instance by setting the appropriate environment variables. A dummy API key is required by most client libraries but is not used by the proxy itself.

**For OpenAI-compatible clients:**
```bash
# For SDK mode
export OPENAI_BASE_URL="http://localhost:8000/sdk/v1"
# For API mode
export OPENAI_BASE_URL="http://localhost:8000/api/v1"

export OPENAI_API_KEY="dummy-key"
```

**For Anthropic-compatible clients:**
```bash
# For SDK mode
export ANTHROPIC_BASE_URL="http://localhost:8000/sdk"
# For API mode
export ANTHROPIC_BASE_URL="http://localhost:8000/api"

export ANTHROPIC_API_KEY="dummy-key"
```

### `curl` Example

```bash
# SDK mode
curl -X POST http://localhost:8000/sdk/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'

# API mode
curl -X POST http://localhost:8000/api/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [{"role": "user", "content": "Hello!"}],
    "max_tokens": 100
  }'
```
More examples are available in the `examples/` directory.

## Endpoints

The proxy exposes endpoints under two prefixes, corresponding to its operating modes.

| Mode | URL Prefix | Description | Use Case |
|------|------------|-------------|----------|
| **SDK** | `/sdk/` | Uses `claude-code-sdk` with its configured tools. | Accessing Claude with local tools. |
| **API** | `/api/` | Direct proxy with header injection. | Full API control, direct access. |

*   **Anthropic:**
    *   `POST /sdk/v1/messages`
    *   `POST /api/v1/messages`
*   **OpenAI-Compatible:**
    *   `POST /sdk/v1/chat/completions`
    *   `POST /api/v1/chat/completions`
*   **Utility:**
    *   `GET /health`
    *   `GET /sdk/models`, `GET /api/models`
    *   `GET /sdk/status`, `GET /api/status`
    *   `GET /oauth/callback`
*   **Observability (Optional):**
    *   `GET /metrics`
    *   `GET /logs/status`, `GET /logs/query`
    *   `GET /dashboard`

## Supported Models

CCProxy supports recent Claude models including Opus, Sonnet, and Haiku variants. The specific models available to you will depend on your Claude account and the features enabled for your subscription.

 * `claude-opus-4-20250514`
 * `claude-sonnet-4-20250514`
 * `claude-3-7-sonnet-20250219`
 * `claude-3-5-sonnet-20241022`
 * `claude-3-5-sonnet-20240620`

## Configuration

Settings can be configured through (in order of precedence):
1. Command-line arguments
2. Environment variables
3. `.env` file
4. TOML configuration files (`.ccproxy.toml`, `ccproxy.toml`, or `~/.config/ccproxy/config.toml`)
5. Default values

For complex configurations, you can use a nested syntax for environment variables with `__` as a delimiter:

```bash
# Server settings
SERVER__HOST=0.0.0.0
SERVER__PORT=8080
# etc.
```

## Securing the Proxy (Optional)

You can enable token authentication for the proxy. This supports multiple header formats (`x-api-key` for Anthropic, `Authorization: Bearer` for OpenAI) for compatibility with standard client libraries.

**1. Generate a Token:**
```bash
ccproxy generate-token
# Output: AUTH_TOKEN=abc123xyz789...
```

**2. Configure the Token:**
```bash
# Set environment variable
export AUTH_TOKEN=abc123xyz789...

# Or add to .env file
echo "AUTH_TOKEN=abc123xyz789..." >> .env
```

**3. Use in Requests:**
When authentication is enabled, include the token in your API requests.
```bash
# Anthropic Format (x-api-key)
curl -H "x-api-key: your-token" ...

# OpenAI/Bearer Format
curl -H "Authorization: Bearer your-token" ...
```

## Observability

`ccproxy` includes an optional but powerful observability suite for monitoring and analytics. When enabled, it provides:

*   **Prometheus Metrics:** A `/metrics` endpoint for real-time operational monitoring.
*   **Access Log Storage:** Detailed request logs, including token usage and costs, are stored in a local DuckDB database.
*   **Analytics API:** Endpoints to query and analyze historical usage data.
*   **Real-time Dashboard:** A live web interface at `/dashboard` to visualize metrics and request streams.

These features are disabled by default and can be enabled via configuration. For a complete guide on setting up and using these features, see the [Observability Documentation](docs/observability.md).

## Troubleshooting

### Common Issues

1.  **Authentication Error:** Ensure you're using the correct mode (`/sdk` or `/api`) for your authentication method.
2.  **Claude Credentials Expired:** Run `ccproxy auth login` to refresh credentials for API mode. Run `claude /login` for SDK mode.
3.  **Missing API Auth Token:** If you've enabled security, include the token in your request headers.
4.  **Port Already in Use:** Start the server on a different port: `ccproxy --port 8001`.
5.  **Model Not Available:** Check that your Claude subscription includes the requested model.

## Contributing

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Documentation

- **[Online Documentation](https://caddyglow.github.io/ccproxy-api)**
- **[API Reference](https://caddyglow.github.io/ccproxy-api/api-reference/overview/)**
- **[Developer Guide](https://caddyglow.github.io/ccproxy-api/developer-guide/architecture/)**

## Support

- Issues: [GitHub Issues](https://github.com/CaddyGlow/ccproxy-api/issues)
- Documentation: [Project Documentation](https://caddyglow.github.io/ccproxy-api)

## Acknowledgments

- [Anthropic](https://anthropic.com) for Claude and the Claude Code SDK
- The open-source community
