Documentation

For coding agents

If you are a coding agent helping a user govern LLM spend, start here. Treat the human as the budget and policy owner. Evaluate one representative workflow in observe mode before recommending enforcement.

⚡ Quickstart

1. Get your project key — Create a project in the Dashboard. You'll receive cp_live_... — save it, it's shown once.

2. Swap your base URL — Point your OpenAI client to the CachePilot endpoint:

3. Read the receipt headers — Every response includes X-CP-* headers proving what policy was applied.

Python / TypeScript SDK:

Anthropic (Claude Fable 5): point the Anthropic SDK at the same base URL with a compound key — cp_live_...:sk-ant-... — and requests route through /v1/messages with the same governance and receipts. On Fable 5, the proxy also strips request params the model rejects (temperature, top_p, top_k) and can inject a cache_control breakpoint when you haven't set one — every change is listed in X-CP-Mutations.

🖥️ Codex CLI

OpenAI Codex CLI works natively with CachePilot. Set up a custom model provider so every Codex session goes through the proxy — policy enforcement, cache optimization, and telemetry included.

1. Set environment variables

CachePilot needs your project key and an OpenAI API key with full api.responses.write scope.

2. Configure Codex

Add this to your ~/.codex/config.toml:

3. Run Codex

That's it. Every Codex request now flows through CachePilot with policy enforcement, cache optimization, and full telemetry. Check your Dashboard to see requests in real time.

Supported models

The proxy supports all OpenAI Responses API models via /v1/responses:

…and all Anthropic models via /v1/messages:

🛡️ Policies

Each project has a PolicyV1 JSON object that controls what the proxy allows. Policies are enforced deterministically before any request reaches the upstream provider, and every change creates a new immutable version — so you can always reconstruct exactly what was applied to a given request from its policy_version and policy_hash.

Shell Access

openai.allow_shell — When false, any request containing {"type":"shell"} or {"type":"computer_use_preview"} is rejected with HTTP 403 before it reaches OpenAI. The telemetry row records shell_requested=true, shell_denied=true.

Skills

Four arrays of skill IDs combine into a deterministic contract:

See the Skills section for the catalog of built-in skill IDs.

Output Budget

Controls the max_output_tokens parameter forwarded to OpenAI.

The final value sent upstream is recorded as applied_max_output_tokens on the telemetry row and echoed in X-CP-Output-Budget-Applied.

Prefix Cache

prefix_cache.mode (DISABLED / AUTO / MANUAL) governs how the proxy derives a stable prompt_cache_key for each request. prompt_cache_key_source selects what that key is seeded from (NONE, PREFIX_HASH, or PROJECT_ID). The goal is to maximize upstream cache hits without leaking content into the key; the exact derivation is an implementation detail of the proxy.

Output Cap Instruction

When output_cap_instruction.enabled is true, the proxy appends a short system-level instruction reinforcing the output budget. Useful for models that treat max_output_tokens as advisory.

Telemetry Controls

telemetry.store_prompts and telemetry.store_outputs both default to false. In the default configuration the proxy is fully content-free — only hashes, counts, and operational metadata are persisted.

🧩 Skills

Skills are the named governance primitives the proxy enforces on every request. Each skill is a small, deterministic contract — the list below is the catalog of built-ins you can reference by ID in a policy's skill arrays.

Skills are grouped into tier bundles — core_free, core_starter, and core_pro — which determine which skills are available on your project's plan. See Pricing for bundle membership.

🎯 Drift & Golden Runs

A golden run is a pinned baseline — any request from the dashboard can be promoted, which captures its policy version, prefix hash, and tool/skill fingerprints as the expected state for that route. Subsequent requests on the same route are compared against the baseline, and any mismatch is recorded as a drift_event.

Drift detection is content-free: it only looks at hashes, so it catches structural changes without ever needing to see your prompts or outputs.

Drift events surface in the dashboard's Determinism and Golden Runs tabs, so you can spot silent prompt or policy regressions before they hit production traffic.

📋 Receipt Headers

Every response from the proxy includes X-CP-* headers. These are your policy receipt — proof of what was enforced, without storing any content.

📊 Telemetry Fields

Every proxied request writes a content-free telemetry row to Postgres. No prompts, no outputs — only operational metadata.

Usage row (per request):

🚀 Deployment

The CachePilot proxy terminates TLS via Caddy. Your API key never touches our storage layer — it's forwarded to OpenAI in-memory during each request.

Endpoint: https://api.cachepilot.clclabs.ai/v1/responses

Health check: https://api.cachepilot.clclabs.ai/health