Cursor BYOK proxy that routes OpenAI-compatible chat completions through Codex (ChatGPT) and Anthropic (Claude) sessions.

Overview • Features • Getting started • Run locally • Configuration • API surface • Troubleshooting

shim is a TanStack Start application that lets Cursor BYOK talk to multiple upstream sessions through a single OpenAI-compatible /v1/chat/completions endpoint. It accepts Cursor's Responses-API-shaped payloads, dispatches them to the configured provider (Codex or Anthropic), applies dashboard-controlled model and reasoning settings, streams replies back as OpenAI chat completion chunks, and records only request metadata in Convex.

The app is made of:

• A local dashboard (React 19 + TanStack Router + Tailwind CSS v4) with a multi-provider console (src/components/console/).
• Thin route handlers under src/routes/ that delegate proxy, OAuth, settings, and health work to src/lib/server/.
• A provider registry under src/lib/server/providers/ that abstracts each upstream (Codex Responses API, Anthropic Messages API) behind a shared interface.
• A self-hosted Convex backend for OAuth tokens, PKCE state, settings, plan-usage snapshots, and request metadata.
• Docker Compose services for Convex, the Convex dashboard, a mandatory Cloudflare Tunnel, and an optional production-like app container.

• Cursor BYOK endpoint — serves POST /v1/chat/completions and GET /v1/models in the shape Cursor expects.
• Multi-provider routing — pluggable Codex and Anthropic providers behind one OpenAI-compatible surface; add more in src/lib/server/providers/.
• Dashboard-controlled model + effort — Cursor enters the sentinel model shim; the dashboard picks the real provider, model, and reasoning effort server-side.
• Live console — activity, provider, routing, and usage panels driven by Convex subscriptions.
• Local onboarding — guided flow for OAuth, tunnel setup, Cursor BYOK config, and connection testing.
• Plan-usage tracking — pull (Codex) and header-driven (Anthropic) strategies, normalized into a shared usage table.
• Metadata-only analytics — counters, latency, token counts, tool counts, cache keys; no request or response bodies persisted.
• Tunnel-aware security — dashboard stays local; the public proxy enforces a CF-Connecting-IP allow-list.
• i18n out of the box — Paraglide-compiled messages for de, en, es, fr (messages/*.json).
• Vite+ toolchain — vp drives dev, build, test, lint, format, and staged checks.

You need:

• Node.js >=22
• pnpm 11.1.2
• Docker Compose for the self-hosted Convex services
• A Codex-capable ChatGPT account and/or a Claude account for OAuth
• A public HTTPS URL for Cursor BYOK, usually via Cloudflare Tunnel

Clone and install:

git clone https://github.com/Firzus/shim.git
cd shim
pnpm install --frozen-lockfile
cp .env.example .env

Set CONVEX_INSTANCE_SECRET in .env before starting Convex — the container refuses to boot without it.

Start Convex and the dashboard backend:

docker compose up -d convex convex-dashboard

After Convex prints its admin key, add it to .env as CONVEX_SELF_HOSTED_ADMIN_KEY, then sync the schema and start the app:

pnpm convex:deploy
pnpm dev

Open http://127.0.0.1:3221 and follow the onboarding flow.

Once onboarding has a public tunnel URL, plug these values into Cursor's custom model setup:

Base URL:   https://your-public-tunnel.example/v1
Model name: shim
API key:    any non-empty string

Cursor rejects localhost and other private network URLs. Point your tunnel ingress at http://host.docker.internal:3221 (Docker) or http://127.0.0.1:3221 (host process) and, when your tunnel provider supports path rules, restrict public ingress to ^/v1/.*.

.env.example is the source of truth for local config — six variables. Ports and other fixed values live in docker-compose.yml.

SHIM_MAX_UPSTREAM_CONCURRENCY (default 3) and LOG_LEVEL (default INFO) are undocumented code-only tuning knobs; set them in the environment only if needed.

docker compose up -d
docker compose --profile prod up -d app

• Default services — local Convex, the Convex dashboard, and the Cloudflare tunnel (cloudflared). The tunnel is mandatory and requires CLOUDFLARE_TUNNEL_TOKEN.
• prod profile — builds and runs the app container behind the same local ports.

pnpm start runs docker compose --profile prod up -d --build --wait: it builds the app image and starts every service — Convex, the Convex dashboard, cloudflared, and the app container — waiting until each is healthy. pnpm stop tears the whole stack back down (docker compose --profile prod down).

On a first boot, run pnpm start once to start Convex, copy the admin key from the Convex container logs into .env as CONVEX_SELF_HOSTED_ADMIN_KEY, run pnpm convex:deploy to sync the schema, then pnpm start again.

Public-facing HTTP endpoints, exposed through the tunnel:

The dashboard talks to the server through TanStack Start server functions (typed RPC, validated with Zod) — see src/lib/api/server-fns.ts: settings read/write, plan-usage refresh, analytics, the connection test, and per-provider OAuth (initLogin, exchangeCallback, getAuthStatus, logout).

convex/                              Convex schema, functions, generated client bindings (read-only)
messages/                            Paraglide source catalogs (de, en, es, fr)
public/                              Manifest and app logos
src/components/                      React UI components
src/components/console/              Multi-provider dashboard console
src/components/ui/                   Reusable shadcn-style primitives
src/lib/                             Shared client utilities (cursor-byok, labels, query client)
src/lib/api/                         Server functions, Zod schemas, query/mutation hooks
src/lib/server/                      Server handlers, Convex client, settings, OAuth, middleware
src/lib/server/providers/            Provider registry + per-provider folders
src/lib/server/providers/codex/      Codex provider (Responses API)
src/lib/server/providers/anthropic/  Anthropic provider (Messages API + Claude Code translation)
src/lib/server/translation/          Shared SSE parser + cross-provider translation helpers
src/routes/                          TanStack Router pages (`/`, `/onboarding`, `/setup`, `/v1/*`, `/api/*`)
vite.config.ts                       Vite+ app, test, lint, format, and staged config

• AGENTS.md — repository-specific coding rules and validation expectations.
• TanStack Start — full-stack React framework powering the dashboard and API routes.
• Convex self-hosting — backend used for settings, OAuth state, counters, and metadata.
• Cloudflare Tunnel — common way to expose the proxy route to Cursor BYOK.
• Vite+ — toolchain accessed through the vp and vpx commands in this repo.
• Paraglide JS — i18n compiler used for messages/*.json.