> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Providers Workspace

> Configure API-key and connector-based upstream routes inside the CLIProxy dashboard

# AI Providers Workspace

The AI Providers workspace at `/cliproxy/ai-providers` is the dashboard surface
for **API-key and connector-based upstream routes inside CLIProxy**. It is the
place to manage non-OAuth provider families that still belong to the proxy
layer.

## Access

```bash theme={null}
ccs config
# Sidebar -> CLIProxy -> AI Providers
# Direct route -> /cliproxy/ai-providers
```

## Source Modes

The page always shows where it is reading and writing provider definitions:

| Mode              | What it means                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| `Local CLIProxy`  | entries come from the local CLIProxy config and are written back into the local top-level YAML sections |
| `Remote CLIProxy` | entries are managed through the remote proxy's management API using the configured management auth      |

## Provider Families

| Family            | Route path                    | Typical use                                                             |
| ----------------- | ----------------------------- | ----------------------------------------------------------------------- |
| Gemini            | `/api/provider/gemini`        | Google Gemini API keys plus optional route defaults                     |
| Codex             | `/api/provider/codex`         | OpenAI or Codex API keys and endpoint overrides                         |
| Claude            | `/api/provider/claude`        | Anthropic-compatible routes, aliases, and filters                       |
| Vertex            | `/api/provider/vertex`        | Vertex AI keys and regional endpoint overrides                          |
| OpenAI-Compatible | `/api/provider/openai-compat` | named connectors for OpenRouter, Together, and custom OpenAI-style APIs |

## Workspace Layout

### Family Rail

The family rail shows readiness at a glance:

* **Ready** means all required secrets are present
* **Needs attention** means the family has entries but at least one is incomplete
* **Empty** means no saved entries yet

### Saved Entries

After choosing a family, the middle list shows the saved entry or entries for
that family, including routing mode and whether secrets are configured.

### Editor

The editor is split into two views:

* **Config / Usage** for guided fields and routing explanations
* **Raw JSON / Preview** for the payload and resulting environment snapshot

The preview includes a global-env indicator so you can see what the connector
would inject before saving it.

## Routing Modes

Entries can stay minimal or become more advanced:

| Mode            | Trigger            | Use it when                                                            |
| --------------- | ------------------ | ---------------------------------------------------------------------- |
| Default runtime | no override fields | the provider family default is already correct                         |
| Direct upstream | `base-url` only    | you want the route to hit a specific upstream endpoint                 |
| Prefixed route  | `prefix` set       | requested model names need a stable prefix rewrite                     |
| Proxy override  | `proxy-url` set    | traffic should pass through another proxy before reaching the upstream |

Headers, excluded models, and explicit model aliases are available for edge
cases, but they are not the minimum working setup.

## API Profiles Vs AI Providers

Use the AI Providers workspace when the route should stay **inside CLIProxy**.
Use [API Profiles](/providers/concepts/api-profiles) when you want a
**CCS-native profile** with its own `.settings.json`, presets, and direct
runtime selection.

## Related

* [CLIProxy API](/features/proxy/cliproxy-api)
* [API Profiles](/providers/concepts/api-profiles)
* [Remote Proxy](/features/proxy/remote-proxy)