pi-cliproxyapi-wellknown

Optional sidecar service for the pi-cliproxyapi Pi extension. Sits next to a CliProxyAPI instance and provides:

• GET /.well-known/pi — classifies /v1/models into Pi-friendly providers (native Anthropic/OpenAI + custom groups), enriched with metadata from models.dev
• GET /api/usage — per-account quota windows (Claude, Codex, Antigravity, Kimi, GitHub Copilot, Gemini CLI)
• GET /healthz — liveness probe

Without this sidecar the plugin still works — it falls back to raw /v1/models with local heuristics. The sidecar adds richer metadata and usage reporting.

Architecture

                   ┌───────────────────────┐
 Pi plugin ───────▶│  CliProxyAPI (:8317)   │◀── this sidecar reads
   │               │  /v1/models            │    /v1/models + /v0/management
   │               │  /v0/management/*      │
   │               └───────────────────────┘
   │               ┌───────────────────────┐
   └──────────────▶│  wellknown (:3458)     │
                   │  /.well-known/pi       │
                   │  /api/usage            │
                   └───────────────────────┘

Routes

Route	Auth	Notes
GET /.well-known/pi	User-Agent: pi-cliproxyapi/<semver>	Model discovery. No keys in response body.
GET /api/usage	X-Plugin-Key: $PI_PLUGIN_USAGE_KEY	503 if management not configured, 401 if key wrong.
GET /healthz	none	{"ok":true}

Setup

1. Environment

Copy .env.example → .env and fill in:

# Required
UPSTREAM_MODELS_URL=http://cliproxyapi:8317/v1/models   # internal Docker network URL
UPSTREAM_TOKEN=<cliproxyapi-api-key>
PI_PUBLIC_BASE_URL=https://proxy.example.com/v1          # the public URL your Pi clients use

# Optional (enables /api/usage)
MANAGEMENT_API_URL=http://cliproxyapi:8317/v0/management
MANAGEMENT_API_KEY=<management-key>
PI_PLUGIN_USAGE_KEY=<generate-a-random-key>              # shared with the Pi plugin

2. Run

Docker Compose (alongside CliProxyAPI):

# Add to your existing docker-compose.yml
services:
  pi-cliproxyapi-wellknown:
    build:
      context: ./pi-cliproxyapi-wellknown
    ports:
      - "127.0.0.1:3458:3458"
    environment:
      UPSTREAM_MODELS_URL: http://cliproxyapi:8317/v1/models
      UPSTREAM_TOKEN: ${UPSTREAM_TOKEN}
      PI_PUBLIC_BASE_URL: ${PI_PUBLIC_BASE_URL}
      MANAGEMENT_API_URL: http://cliproxyapi:8317/v0/management
      MANAGEMENT_API_KEY: ${MANAGEMENT_API_KEY}
      PI_PLUGIN_USAGE_KEY: ${PI_PLUGIN_USAGE_KEY}
    depends_on:
      cliproxyapi:
        condition: service_healthy
    networks:
      - your-network

Standalone Docker:

docker build -t pi-cliproxyapi-wellknown .
docker run --rm -p 3458:3458 --env-file .env pi-cliproxyapi-wellknown

Local dev:

export $(grep -v '^#' .env | xargs)
python3 src/server.py

3. Reverse proxy

Route /.well-known/pi and /api/usage on your public domain to this service (port 3458). Other paths (/v1/*) continue to go to CliProxyAPI.

4. Pi plugin config

In /cliproxy-setup, set the endpoint to your public domain (e.g. https://proxy.example.com/v1). The plugin auto-discovers /.well-known/pi from the same origin.

For /cliproxy-usage, set the usage key to the same PI_PLUGIN_USAGE_KEY value.

Tests

python3 -m unittest discover -s tests -v

Tests stub both CliProxyAPI endpoints with an in-process HTTP server — no network needed.

Layout

src/
  server.py             HTTP routes, ModelsCache, settings
  builders.py           build_discovery_document, build_usage_document
  models_catalog.py     live-fetch from models.dev with 24h TTL + fallback
  cliproxyapi_quotas.py vendored quota fetchers for supported providers
tests/
  test_server.py        10 stubbed end-to-end tests
Dockerfile              multi-stage (tests run at build time)
compose.yaml            standalone compose example
.env.example            all environment variables documented