/using-ccproxy-api

name: using-ccproxy-api
description: >-
  Guides users through ccproxy as an OpenAI-compatible and Anthropic-compatible LLM API server
  with SDK integration, OAuth authentication, sentinel key substitution, model routing, and
  troubleshooting. Use when installing ccproxy, configuring SDK clients (Anthropic, OpenAI,
  LiteLLM, Agent SDK) against ccproxy, setting up per-project instances, debugging authentication
  errors, setting up OAuth token forwarding, or understanding the hook pipeline and shaping system.

Using ccproxy as an LLM API Server

ccproxy exposes an OpenAI-compatible and Anthropic-compatible API via a mitmproxy-based interceptor. Any SDK or HTTP client that supports custom `base_url` can use it.

Installation

System-wide (Home Manager)

Add ccproxy as a flake input and enable the Home Manager module:

# flake.nix
inputs.ccproxy.url = "github:starbaser/ccproxy";

# home configuration
programs.ccproxy = {
  enable = true;
  settings = {
    # Override defaults here (port, providers, transforms, etc.)
  };
};

This installs the `ccproxy` binary, generates sibling `ccproxy.yaml` and LiteLLM-compatible `config.yaml` files from Nix, and creates a `systemd --user` service that auto-restarts when either changes.

Standalone (any Linux)

# Clone and enter devShell
git clone https://github.com/starbaser/ccproxy
cd ccproxy
nix develop   # or: direnv allow

# Initialize config
ccproxy init          # copies both templates to ~/.config/ccproxy/
ccproxy init --force  # overwrites both existing files

# Edit native services and model declarations
$EDITOR ~/.config/ccproxy/ccproxy.yaml
$EDITOR ~/.config/ccproxy/config.yaml

# Start
ccproxy start

Per-project instance

Each project can run its own ccproxy with isolated config, port, and transforms via the flake's `mkConfig`. Use `ccproxy.defaultSettings.settings` (top-level, no `${system}` selector needed) as the base to inherit all defaults (hooks, shaping, providers, otel).

# project flake.nix
{
  inputs.ccproxy.url = "github:starbaser/ccproxy";
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  inputs.flake-utils.url = "github:numtide/flake-utils";

  outputs = { self, nixpkgs, flake-utils, ccproxy }:
    let
      defaults = ccproxy.defaultSettings.settings;
    in
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
        proxyConfig = ccproxy.lib.${system}.mkConfig {
          settings = {
            port = 4010;  # per-project: use 4010+ to avoid collisions
            inspector = {
              port = 8090;
              cert_dir = "./.ccproxy";
            };
            lightllm = {
              transforms = [
                { match_path = "/v1/messages"; action = "redirect";
                  dest_provider = "anthropic"; dest_base_url = "https://api.anthropic.com";
                  dest_path = "/v1/messages"; }
              ] ++ defaults.lightllm.transforms;
            };
          };
        };
      in {
        devShells.default = pkgs.mkShell {
          packages = with pkgs; [
            ccproxy.packages.${system}.default
            just process-compose
          ];
          shellHook = proxyConfig.shellHook;
        };
      });
}

`mkConfig` generates Nix-store `ccproxy.yaml` and `config.yaml` files; its `shellHook` symlinks both into `.ccproxy/` and exports `CCPROXY_CONFIG_DIR`. The `.envrc` just needs `use flake`.

Add `.ccproxy/` to `.gitignore` — the directory contains a Nix-generated symlink that is machine-specific and regenerated on `nix develop`:

# .gitignore
.ccproxy/

Port assignment conventions

| Port | Use | |------|-----| | 4000 | System-wide ccproxy (Home Manager, default) | | 4001 | ccproxy project's own devShell | | 4010+ | Per-project instances | | 8083 | System inspector UI (default) | | 8084 | ccproxy dev inspector | | 8090+ | Per-project inspector UI |

Running the instance

# Foreground
ccproxy start

# Via process-compose (recommended for dev)
just up       # process-compose up --detached
just down     # process-compose down

# Check health
ccproxy status              # Rich panel
ccproxy status --json       # Machine-readable
ccproxy status --proxy      # Exit 0 if proxy up, 1 if down
ccproxy status --inspect    # Exit 0 if inspector up, 2 if down

process-compose.yml

Use `ccproxy status --proxy` as the readiness probe so dependent processes wait for the proxy to be healthy:

# process-compose.yml
version: "0.5"

processes:
  ccproxy:
    command: "ccproxy start"
    readiness_probe:
      exec:
        command: "ccproxy status --proxy"
      initial_delay_seconds: 5
      period_seconds: 30
      timeout_seconds: 10
      failure_threshold: 6
    availability:
      restart: on_failure
      backoff_seconds: 2
      max_restarts: 5

  myapp:
    command: "python -m myapp"
    depends_on:
      ccproxy:
        condition: process_healthy

Wiring SDK clients

Point any SDK at the per-project port with a sentinel key:

import anthropic

client = anthropic.Anthropic(
    api_key="sk-ant-oat-ccproxy-anthropic",
    base_url="http://localhost:4010",  # per-project port
)

Or via environment variables in `shellHook` / `.envrc`:

export ANTHROPIC_BASE_URL="http://localhost:4010"
export ANTHROPIC_API_KEY="sk-ant-oat-ccproxy-anthropic"

Configuration

Configuration lives under `$CCPROXY_CONFIG_DIR` (default `~/.config/ccproxy/`): `ccproxy.yaml` owns native services and `config.yaml` owns LiteLLM-compatible model declarations.

ccproxy:
  host: 127.0.0.1
  port: 4000

  providers:
    anthropic:
      auth:
        type: command
        command: "jq -r '.claudeAiOauth.accessToken' ~/.claude/.credentials.json"
      base_url: https://api.anthropic.com
      path: /v1/messages
      type: anthropic
    gemini:
      auth:
        type: command
        command: "jq -r '.access_token'