ocx-cursor 0.4.0 → 0.5.0

package/README.md

@@ -3,20 +3,18 @@
 [![npm version](https://img.shields.io/npm/v/ocx-cursor.svg)](https://www.npmjs.com/package/ocx-cursor)
 [![CI](https://github.com/hiddenest/opencodex-cursor-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/hiddenest/opencodex-cursor-bridge/actions/workflows/ci.yml)
 
-Use active [OpenCodex](https://github.com/lidge-jun/opencodex) models in Cursor through its custom OpenAI endpoint. The package runs a local gateway, registers the endpoint in Cursor, and keeps Cursor's custom model list in sync.
+Use active [OpenCodex](https://github.com/lidge-jun/opencodex) models in Cursor through its custom OpenAI endpoint. The package runs a loopback-only gateway, registers it in Cursor, and keeps Cursor's custom model list in sync.
 
 ## Requirements
 
 - macOS with Cursor installed at `/Applications/Cursor.app`
 - Node.js 22.5 or newer
-- A domain using Cloudflare DNS, or another HTTPS reverse proxy
+- OpenCodex installed and configured
 
 Launch Cursor and sign in once before setup. Cursor creates the Safe Storage key that the installer uses to encrypt the gateway API key.
 
 ## Setup
 
-The commands below use `cursor-api.example.com`. Replace it with a hostname under your own Cloudflare-managed domain.
-
 ### 1. Install OpenCodex
 
 [OpenCodex](https://github.com/lidge-jun/opencodex) requires Node.js 18 or newer and bundles its own Bun runtime. This bridge requires Node.js 22.5 or newer, so install Node.js 22 or later before continuing.
@@ -37,32 +35,22 @@ if [[ "$(command -v ocx)" != "$HOME/.local/bin/ocx" ]]; then
 fi
 ```
 
-`ocx init` opens the interactive provider setup. You can also open the dashboard and add or sign in to a provider there:
+`ocx init` opens the interactive provider setup. You can also configure providers through the dashboard or terminal:
 
 ```bash
 ocx gui
-```
-
-OAuth-backed providers can also be connected from the terminal:
-
-```bash
 ocx login <provider>
 ```
 
-Install OpenCodex as a login service, then check it:
+Install OpenCodex as a login service, then verify it:
 
 ```bash
 ocx service install
 ocx service status
-```
-
-OpenCodex listens on `http://127.0.0.1:10100` by default. Confirm that its model endpoint responds:
-
-```bash
 curl http://127.0.0.1:10100/v1/models
 ```
 
-If you configured OpenCodex with a service API token, include that token:
+If you configured OpenCodex with a service API token, include it in the request:
 
 ```bash
 curl \
@@ -70,68 +58,9 @@ curl \
   http://127.0.0.1:10100/v1/models
 ```
 
-See the [OpenCodex documentation](https://lidge-jun.github.io/opencodex/) for provider-specific login and model configuration.
-
-### 2. Create a Cloudflare Tunnel
-
-Cursor requires an HTTPS custom OpenAI endpoint. A [Cloudflare Tunnel](https://developers.cloudflare.com/tunnel/) can publish the bridge on HTTPS without opening an inbound port on your router.
-
-Add your domain to Cloudflare and point its nameservers to Cloudflare. Then install `cloudflared` on the Mac that runs OpenCodex and Cursor:
+See the [OpenCodex documentation](https://lidge-jun.github.io/opencodex/) for provider-specific setup.
 
-```bash
-brew install cloudflared
-cloudflared tunnel login
-```
-
-The login command opens Cloudflare in your browser and writes `~/.cloudflared/cert.pem`. Create a [locally-managed named tunnel](https://developers.cloudflare.com/tunnel/advanced/local-management/create-local-tunnel/):
-
-```bash
-cloudflared tunnel create ocx-cursor
-cloudflared tunnel list
-```
-
-Copy the tunnel UUID printed by the command. It also creates a credentials file named `<TUNNEL_UUID>.json` under `~/.cloudflared`.
-
-Create `~/.cloudflared/config.yml`. Replace the UUID, macOS username, and hostname in this example:
-
-```yaml
-# ~/.cloudflared/config.yml
-tunnel: YOUR_TUNNEL_UUID
-credentials-file: /Users/YOUR_MACOS_USERNAME/.cloudflared/YOUR_TUNNEL_UUID.json
-
-ingress:
-  - hostname: cursor-api.example.com
-    service: http://127.0.0.1:10101
-  - service: http_status:404
-```
-
-Create the DNS CNAME for the public hostname. The command adds the record to Cloudflare, so you do not need to create it separately in the dashboard:
-
-```bash
-cloudflared tunnel route dns ocx-cursor cursor-api.example.com
-```
-
-Validate the configuration and start the tunnel in the foreground:
-
-```bash
-cloudflared tunnel ingress validate
-cloudflared tunnel ingress rule https://cursor-api.example.com
-cloudflared tunnel run ocx-cursor
-```
-
-The public hostname returns `502 Bad Gateway` until the bridge is installed in the next step. Keep this terminal open while testing.
-
-For login-time startup on macOS, stop the foreground process and install the `cloudflared` launch agent:
-
-```bash
-cloudflared service install
-```
-
-Use `sudo cloudflared service install` only if you want a system launch daemon that starts at boot. That mode reads its configuration from `/etc/cloudflared`, not your home directory. See Cloudflare's [macOS service guide](https://developers.cloudflare.com/tunnel/advanced/local-management/as-a-service/macos/) for the required file locations.
-
-This package does not create, modify, or remove the Cloudflare Tunnel.
-
-### 3. Install the Cursor bridge
+### 2. Install the Cursor bridge
 
 Quit Cursor completely, confirm that OpenCodex is running, then initialize the bridge:
 
@@ -139,51 +68,47 @@ Quit Cursor completely, confirm that OpenCodex is running, then initialize the b
 npx ocx-cursor init
 ```
 
-Enter the Cloudflare Tunnel hostname when prompted. The `https://` prefix and `/v1` suffix are optional:
-
-```text
-Cloudflare Tunnel URL (for example, https://cursor-api.example.com): https://cursor-api.example.com
-```
-
-The installer starts the local bridge and tests two routes through Cloudflare before it changes Cursor:
-
-- `GET /healthz` confirms that the hostname reaches this bridge.
-- Authenticated `GET /v1/models` confirms that request headers reach the bridge and OpenCodex responds.
-
-If either check fails, `init` stops before writing Cursor's API settings. The local bridge stays running so you can fix the tunnel and rerun the command.
-
-For scripts and unattended setup, pass the URL directly:
-
-```bash
-npx ocx-cursor init \
-  --base-url https://cursor-api.example.com/v1
-```
-
-`init` performs these actions:
+No tunnel or public domain is required. `init` uses `http://127.0.0.1:10101/v1` and performs these actions:
 
 1. Generates a gateway API key in `~/.opencodex/cursor-bridge/secret`.
 2. Installs the `com.opencodex.cursor-bridge` LaunchAgent.
-3. Tests the Cloudflare Tunnel and OpenCodex model endpoint.
+3. Tests the local gateway and OpenCodex model endpoint.
 4. Stores the key in Cursor with macOS Safe Storage encryption.
-5. Registers the HTTPS URL as Cursor's OpenAI base URL.
+5. Registers the local gateway as Cursor's OpenAI base URL.
 6. Adds active OpenCodex models to Cursor under `opencodex/*`.
+7. Enables Cursor's local-agent mode and installs the model metadata patches described below.
+
+`init` patches ten JavaScript files inside `Cursor.app`:
 
-The installer links `ocx-cursor` into `~/.local/bin`. Add that directory to `PATH` if your shell does not include it:
+- Eight Cursor bundles get the local-mode build flag.
+- The Desktop and Glass workbench bundles retain OpenCodex display names, effort choices, and Fast metadata when Cursor refreshes its server catalog.
+- Both local-agent runtimes display names such as `GPT 5.6 Sol` while keeping `opencodex/gpt-5.6-sol` as the request ID.
+
+Original files are copied to `~/.opencodex/cursor-bridge/cursor-app-backups` before they are changed. The LaunchAgent watches the same files and reapplies the patches after a Cursor update, once Cursor has quit.
+
+> [!WARNING]
+> Patching `Cursor.app` invalidates its vendor code signature. Cursor may show “Your Cursor installation appears to be corrupt.” This is expected for this integration. Reinstall Cursor to restore an unmodified, vendor-signed app.
+
+The installer links `ocx-cursor` into `~/.local/bin`. Add that directory to `PATH` if needed:
 
 ```bash
 export PATH="$HOME/.local/bin:$PATH"
 ```
 
-Check the local gateway and public hostname before opening Cursor:
+Check the service before opening Cursor:
 
 ```bash
 ocx-cursor status
-curl https://cursor-api.example.com/healthz
+curl http://127.0.0.1:10101/healthz
 ```
 
-The status output should show `Service: running` and `Gateway: healthy`. The public health endpoint should return JSON with `"status":"ok"`.
+The status output should show `Service: running` and `Gateway: healthy`. Open Cursor after both checks pass.
 
-Open Cursor after both checks pass. Models with known reasoning controls show an effort value in the picker. Use `Shift+Command+/` to cycle it.
+To use an explicit HTTPS reverse proxy instead, pass its URL directly. This is optional and not used by the default setup:
+
+```bash
+npx ocx-cursor init --base-url https://cursor-api.example.com/v1
+```
 
 ### Fast mode
 
@@ -195,30 +120,28 @@ Fast requires an OpenCodex version that preserves `service_tier` on its Chat Com
 
 ```text
 Cursor
-  -> https://cursor-api.example.com/v1
-  -> Cloudflare Tunnel
-  -> OpenCodex Cursor Bridge on 127.0.0.1:10101
-  -> OpenCodex on 127.0.0.1:10100
+  -> OpenCodex Cursor Bridge on http://127.0.0.1:10101/v1
+  -> OpenCodex on http://127.0.0.1:10100
   -> configured provider
 ```
 
-The gateway API key is generated during `init` and stored in Cursor with macOS Safe Storage encryption. The bridge requires this bearer token on every `/v1/*` request. Keep the bridge bound to `127.0.0.1`; `cloudflared` can reach it without exposing port `10101` to the local network.
+The gateway API key is generated during `init` and stored in Cursor with macOS Safe Storage encryption. The bridge requires this bearer token on every `/v1/*` request and binds to `127.0.0.1` by default.
 
 ## Commands
 
 | Command | Purpose |
 | --- | --- |
-| `ocx-cursor init [--base-url URL]` | Install the service, prompt for and test the tunnel, configure Cursor, and sync models. Cursor must be closed. |
-| `ocx-cursor install` | Reinstall or restart the LaunchAgent without changing Cursor's API settings. |
-| `ocx-cursor update` | Download the latest `ocx-cursor` release from npm, reinstall the service, and sync models. |
+| `ocx-cursor init [--base-url URL]` | Install the service, test the endpoint, configure Cursor, and sync models. Cursor must be closed. |
+| `ocx-cursor install` | Reinstall the LaunchAgent and verify app patches, or queue them until Cursor quits. |
+| `ocx-cursor update` | Download the latest release from npm, reinstall the service, verify patches, and sync models. |
 | `ocx-cursor sync` | Refresh the active model catalog. The service queues the update while Cursor runs. |
 | `ocx-cursor launch` | Experimentally launch Cursor with live effort and Fast metadata injection. Keep the command running. |
 | `ocx-cursor status` | Show service health, model count, and pending sync state. |
 | `ocx-cursor uninstall` | Remove the LaunchAgent, command link, and bridge home directory. |
 
-`uninstall` leaves Cursor's custom endpoint and model records in its state database.
+`uninstall` leaves Cursor's custom endpoint, model records, and app patches in place. Reinstall Cursor if you want to restore its original signed files.
 
-`update` preserves the existing gateway API key and Cursor endpoint. It updates only this companion package; update OpenCodex separately with your package manager.
+`update` preserves the existing gateway API key and Cursor endpoint. If Cursor is running, app patches and model sync are queued until it quits. The command updates only this companion package; update OpenCodex separately with your package manager.
 
 ## Model mapping
 
@@ -229,9 +152,13 @@ anthropic/claude-sonnet-5  -> opencodex/claude-sonnet-5
 gpt-5.6-sol                -> opencodex/gpt-5.6-sol
 ```
 
-The catalog includes models returned by OpenCodex's active `/v1/models` endpoint. It excludes the OpenCodex `cursor/*` provider to avoid duplicating Cursor's own models.
+The catalog includes every model returned by OpenCodex's active `/v1/models` endpoint, including models from the `cursor/*` provider. Cursor-backed aliases use the `opencodex/cursor/*` prefix so they remain distinct from Cursor's built-in entries.
+
+Cursor removes custom effort metadata from its database during startup. The companion LaunchAgent patches the Desktop and Glass catalog storage steps so `opencodex/*` display names, effort, and Fast metadata survive server refreshes. It monitors the installed bundles and local-agent runtimes, then reapplies their patches when Cursor replaces the app during an update.
+
+`init`, `install`, and `update` also patch Cursor's local model runtimes so provider refreshes keep human-readable names such as `GPT 5.6 Sol` while requests continue using stable `opencodex/*` model IDs.
 
-Cursor removes custom effort metadata from its database during startup. The LaunchAgent writes that metadata back after Cursor exits, once all Cursor Helper processes have stopped.
+Cursor sends some built-in function tools with `strict: true` even when their JSON schema is not valid for strict mode. The gateway changes that flag to `false` for OpenCodex requests, preventing errors such as `additionalProperties is required to be supplied and to be false` without changing tool arguments.
 
 ### Experimental live model metadata
 
@@ -241,16 +168,16 @@ Cursor removes custom effort metadata from its database during startup. The Laun
 ocx-cursor launch
 ```
 
-Keep the command running for the lifetime of Cursor. This does not modify `Cursor.app`, but it depends on Cursor's private workbench code and currently supports Cursor 3.14.7. The command stops with a compatibility error when it cannot find the expected catalog hook.
+Keep the command running for the lifetime of Cursor. This does not modify `Cursor.app`, but it depends on Cursor's private workbench code and supports only known Cursor builds.
 
 ## Configuration
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `OCX_CURSOR_BASE_URL` | Stored Cursor URL | Prompt default, or endpoint for non-interactive `init`, when `--base-url` is absent. |
+| `OCX_CURSOR_BASE_URL` | `http://127.0.0.1:10101/v1` | Endpoint used by `init` when `--base-url` is absent. |
 | `OCX_CURSOR_HOME` | `~/.opencodex/cursor-bridge` | Service state, API key, catalog, and logs. |
 | `OCX_CURSOR_HOST` | `127.0.0.1` | Local gateway bind address. |
-| `OCX_CURSOR_PORT` | `10101` | Local gateway port. |
+| `OCX_CURSOR_PORT` | `10101` | Local gateway port. Also changes the default Cursor endpoint. |
 | `OCX_BIN` | `~/.local/bin/ocx` | OpenCodex CLI path. |
 
 The gateway accepts these routes:
@@ -260,59 +187,48 @@ The gateway accepts these routes:
 - `POST /v1/responses` and `/v1/responses/compact`
 - `POST /v1/messages`
 
-The gateway requires its generated bearer token on each `/v1/*` request. It binds to loopback unless you change `OCX_CURSOR_HOST`.
-
 ## Troubleshooting
 
-### The public hostname returns 502
+### Cursor returns 401
 
-The tunnel is running, but it cannot reach the local bridge. Check the bridge and its logs:
+Quit Cursor and run `init` again. It preserves the bridge key, tests the local endpoint, and writes the matching encrypted value back to Cursor:
 
 ```bash
-ocx-cursor status
-tail -n 100 ~/.opencodex/cursor-bridge/service.error.log
-tail -n 100 ~/.opencodex/cursor-bridge/service.log
+npx ocx-cursor init
 ```
 
-Confirm that the tunnel ingress points to `http://127.0.0.1:10101`, then restart the bridge if needed:
+### The local gateway is unavailable
+
+Check the service and logs, then reinstall it if needed:
 
 ```bash
+ocx-cursor status
+tail -n 100 ~/.opencodex/cursor-bridge/service.error.log
+tail -n 100 ~/.opencodex/cursor-bridge/service.log
 ocx-cursor install
 ```
 
-### Cloudflare returns error 1016
-
-The DNS record exists, but no tunnel connector is online. Check the named tunnel and start it:
-
-```bash
-cloudflared tunnel info ocx-cursor
-cloudflared tunnel run ocx-cursor
-```
+### Models or effort options are missing
 
-If you installed the login service, inspect it with:
+Quit Cursor and run:
 
 ```bash
-launchctl print "gui/$(id -u)/com.cloudflare.cloudflared"
+ocx-cursor sync
+ocx-cursor status
 ```
 
-### Cursor returns 401
-
-Run `init` again while Cursor is closed. It preserves the bridge key, retests the tunnel, and writes the matching encrypted value back to Cursor:
-
-```bash
-npx ocx-cursor init
-```
+If the status shows a pending sync, wait until every Cursor Helper process has exited. The service applies the queued catalog automatically.
 
-### Models or effort options are missing
+### Patches are missing after a Cursor update
 
-Cursor must be closed before its local model database can be changed. Quit Cursor and run:
+Quit every Cursor window and wait for its Helper processes to stop. The LaunchAgent detects replaced app files and reapplies local mode, metadata, and display-name patches. Check the result with:
 
 ```bash
-ocx-cursor sync
-ocx-cursor status
+ocx-cursor install
+tail -n 100 ~/.opencodex/cursor-bridge/service.log
 ```
 
-If the status shows a pending sync, wait until every Cursor Helper process has exited. The service applies the queued catalog automatically.
+The patcher stops without modifying a file when a Cursor release no longer matches its known code structure. Check `service.error.log` in that case.
 
 ### OpenCodex models cannot be loaded
 
@@ -338,7 +254,7 @@ The code uses `node:sqlite`, so development requires Node.js 22.5 or newer.
 
 ## Compatibility
 
-The package writes Cursor's local state database and uses Cursor's Safe Storage format. Cursor does not document either interface. A Cursor update can change them.
+The package writes Cursor's local state database, uses Cursor's Safe Storage format, and modifies private code inside `Cursor.app`. Cursor does not document these interfaces. A Cursor update can change them.
 
 The current release supports macOS. It does not configure Windows Credential Manager, Linux keyrings, or system services outside launchd.
 

package/bin/ocx-cursor.mjs

@@ -2,21 +2,20 @@
 
 import { readFile } from "node:fs/promises";
 import process from "node:process";
-import { createInterface } from "node:readline/promises";
-import { configureCursorOpenAI, storedCursorOpenAIBaseUrl } from "../src/cursor-config.mjs";
+import { configureCursorOpenAI } from "../src/cursor-config.mjs";
 import { cursorIsRunning } from "../src/cursor-state.mjs";
 import { installService, prepareInstallSecret, serviceStatus, uninstallService, updateService } from "../src/install.mjs";
-import { cursorOpenAIBaseUrl, pendingFile } from "../src/paths.mjs";
+import { cursorLocalBaseUrl, cursorOpenAIBaseUrl, pendingFile } from "../src/paths.mjs";
 import { runService } from "../src/service.mjs";
-import { normalizeBaseUrl, testTunnel } from "../src/setup.mjs";
+import { normalizeBaseUrl, testEndpoint } from "../src/setup.mjs";
 import { loadCatalogSnapshot, syncNow } from "../src/sync.mjs";
 import { findAvailableDebugPort, launchCursorForInjection, runRuntimeInjector } from "../src/runtime-injector.mjs";
 
 const usage = `OpenCodex Cursor Bridge
 
 Usage:
-  ocx-cursor init [--base-url <https-url>]
-                        Install the service, test the tunnel, configure Cursor,
+  ocx-cursor init [--base-url <url>]
+                        Install the service, test the endpoint, configure Cursor,
                         and sync models
   ocx-cursor install    Install and start the macOS companion service
   ocx-cursor update     Install the latest companion release and restart it
@@ -37,19 +36,7 @@ function argumentValue(name) {
 
 async function requestedBaseUrl() {
   const supplied = argumentValue("--base-url");
-  const fallback = cursorOpenAIBaseUrl || storedCursorOpenAIBaseUrl();
-  if (supplied) return normalizeBaseUrl(supplied);
-  if (!process.stdin.isTTY || !process.stdout.isTTY) return normalizeBaseUrl(fallback);
-
-  const prompt = fallback
-    ? `Cloudflare Tunnel URL [${fallback}]: `
-    : "Cloudflare Tunnel URL (for example, https://cursor-api.example.com): ";
-  const readline = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    return normalizeBaseUrl((await readline.question(prompt)).trim() || fallback);
-  } finally {
-    readline.close();
-  }
+  return normalizeBaseUrl(supplied || cursorOpenAIBaseUrl || cursorLocalBaseUrl);
 }
 
 async function pendingCount() {
@@ -70,6 +57,15 @@ function printSync(result) {
   }
 }
 
+function printCursorPatches(result) {
+  if (result.cursorPatches === null) {
+    process.stdout.write("Cursor app patches will be applied after Cursor quits.\n");
+    return;
+  }
+  const changed = result.cursorPatches.filter(({ status }) => status === "patched").length;
+  process.stdout.write(`Verified ${result.cursorPatches.length} Cursor app patches (${changed} changed).\n`);
+}
+
 async function main() {
   const command = process.argv[2] || "help";
   if (["help", "--help", "-h"].includes(command)) {
@@ -85,6 +81,7 @@ async function main() {
   if (command === "install") {
     const installed = await installService();
     process.stdout.write(`Installed ${installed.launchAgentFile} (API key ${installed.secretStatus}).\nCLI: ${installed.cliLinkFile}\n`);
+    printCursorPatches(installed);
     printSync(await syncNow());
     process.stdout.write("Endpoint: http://127.0.0.1:10101/v1\n");
     return;
@@ -97,14 +94,15 @@ async function main() {
     const prepared = await prepareInstallSecret();
     const installed = await installService();
     process.stdout.write(`Installed ${installed.launchAgentFile} (API key ${prepared.secretStatus}).\nCLI: ${installed.cliLinkFile}\n`);
-    process.stdout.write(`Testing Cloudflare Tunnel: ${new URL(baseUrl).origin}\n`);
-    let tunnel;
+    printCursorPatches(installed);
+    process.stdout.write(`Testing endpoint: ${new URL(baseUrl).origin}\n`);
+    let endpoint;
     try {
-      tunnel = await testTunnel(baseUrl, prepared.secret);
+      endpoint = await testEndpoint(baseUrl, prepared.secret);
     } catch (error) {
-      throw new Error(`${error.message}\nThe bridge service is running locally. Fix the tunnel and rerun ocx-cursor init.`);
+      throw new Error(`${error.message}\nThe bridge service is running locally. Fix the endpoint and rerun ocx-cursor init.`);
     }
-    process.stdout.write(`Tunnel is ready (${tunnel.modelCount} models reachable).\n`);
+    process.stdout.write(`Endpoint is ready (${endpoint.modelCount} models reachable).\n`);
     const configured = await configureCursorOpenAI({
       secret: prepared.secret,
       baseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocx-cursor",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "OpenCodex companion service for Cursor custom models",
   "keywords": [
     "opencodex",

package/src/catalog.mjs

@@ -80,7 +80,7 @@ export function normalizeActiveCatalog(configured, active, fastModelIds = new Se
   const models = new Map();
 
   for (const model of active) {
-    if (typeof model?.id !== "string" || model.owned_by === "opencodex" || model.id.startsWith("cursor/")) continue;
+    if (typeof model?.id !== "string" || model.owned_by === "opencodex") continue;
     const configuredModel = configuredById.get(model.id);
     const provider = model.id.includes("/") ? model.id.split("/", 1)[0] : String(model.owned_by || "openai").toLowerCase();
     const inputModalities = Array.isArray(configuredModel?.inputModalities)

package/src/cursor-patch.mjs

@@ -0,0 +1,231 @@
+import { createHash } from "node:crypto";
+import { chmod, copyFile, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import {
+  cursorBundleFiles,
+  cursorGlassWorkbenchFile,
+  cursorLocalRuntimeFiles,
+  cursorPatchBackupDirectory,
+  cursorWorkbenchFile,
+} from "./paths.mjs";
+
+export const cursorPatchMarker = "/*ocx-cursor-model-metadata-v3*/";
+export const legacyCursorPatchMarker = "/*ocx-cursor-model-metadata*/";
+export const cursorLocalModeDisabled = "localMode:!1";
+export const cursorLocalModeEnabled = "localMode:!0";
+export const cursorLocalRuntimePatchMarker = "/*ocx-cursor-local-model-display*/";
+
+export function isCursorModelMetadataBundle(file) {
+  return file === cursorWorkbenchFile || file === cursorGlassWorkbenchFile;
+}
+
+const catalogNormalization = /(?<normalization>\b(?<catalog>[A-Za-z_$][\w$]*)=\k<catalog>\.map\((?<item>[A-Za-z_$][\w$]*)=>(?<plain>[A-Za-z_$][\w$]*)\(\k<item>\)\)),(?=(?<batch>[A-Za-z_$][\w$]*)\(\(\)=>\{this\._reactiveStorageService\.setApplicationUserPersistentStorage\("availableDefaultModels2",\k<catalog>\))/g;
+const previousCatalogInjection = /\/\*ocx-cursor-model-metadata(?:-v2)?\*\/(?<catalog>[A-Za-z_$][\w$]*)=\k<catalog>\.map\(ocxCursorModel=>\{.*?\}\),(?=(?<batch>[A-Za-z_$][\w$]*)\(\(\)=>\{this\._reactiveStorageService\.setApplicationUserPersistentStorage\("availableDefaultModels2",\k<catalog>\))/g;
+const localModelConstructor = /function (?<functionName>[A-Za-z_$][\w$]*)\(e,t\)\{return new (?<modelType>[A-Za-z_$][\w$]*\.[A-Za-z_$][\w$]*)\(\{modelId:e,displayModelId:e,displayName:null!=t\?t:e,displayNameShort:null!=t\?t:e,aliases:\[\]\}\)\}/g;
+const transientPatchErrorCodes = new Set(["EACCES", "EBUSY", "EPERM"]);
+
+function metadataInjection(catalog) {
+  return `${cursorPatchMarker}${catalog}=${catalog}.map(ocxCursorModel=>{if(!ocxCursorModel.name.startsWith("opencodex/"))return ocxCursorModel;const ocxCursorStored=(this._reactiveStorageService.applicationUserPersistentStorage.availableDefaultModels2??[]).find(ocxCursorCandidate=>ocxCursorCandidate?.name===ocxCursorModel.name);const ocxCursorDisplayWords={claude:"Claude",codex:"Codex",composer:"Composer",deepseek:"DeepSeek",fable:"Fable",fast:"Fast",flash:"Flash",gpt:"GPT",grok:"Grok",hy3:"HY3",kimi:"Kimi",luna:"Luna",max:"Max",mimo:"MiMo",mini:"Mini",opus:"Opus",pro:"Pro",qwen:"Qwen",sol:"Sol",sonnet:"Sonnet",spark:"Spark",terra:"Terra"};const ocxCursorDisplayName=ocxCursorModel.name.split("/").at(-1).split("-").map(ocxCursorWord=>{if(ocxCursorDisplayWords[ocxCursorWord])return ocxCursorDisplayWords[ocxCursorWord];const ocxCursorAttached=/^(qwen|kimi|gpt|claude|grok)(\\d+(?:\\.\\d+)*)$/.exec(ocxCursorWord);if(ocxCursorAttached)return ocxCursorDisplayWords[ocxCursorAttached[1]]+" "+ocxCursorAttached[2];if(/^v\\d/i.test(ocxCursorWord))return"V"+ocxCursorWord.slice(1);if(/^k\\d/i.test(ocxCursorWord))return"K"+ocxCursorWord.slice(1);if(/^\\d/.test(ocxCursorWord))return ocxCursorWord;return ocxCursorWord.slice(0,1).toUpperCase()+ocxCursorWord.slice(1)}).join(" ");const ocxCursorPrettyLabel=ocxCursorValue=>typeof ocxCursorValue==="string"?ocxCursorValue.split(ocxCursorModel.name).join(ocxCursorDisplayName):ocxCursorValue;const ocxCursorVariants=(ocxCursorStored?.variants??ocxCursorModel.variants??[]).map(ocxCursorVariant=>({...ocxCursorVariant,displayName:ocxCursorPrettyLabel(ocxCursorVariant.displayName),displayNameOutsidePicker:ocxCursorPrettyLabel(ocxCursorVariant.displayNameOutsidePicker)}));return{...ocxCursorModel,clientDisplayName:ocxCursorDisplayName,inputboxShortModelName:ocxCursorDisplayName,parameterDefinitions:ocxCursorStored?.parameterDefinitions??ocxCursorModel.parameterDefinitions??[],variants:ocxCursorVariants,legacySlugs:ocxCursorStored?.legacySlugs??ocxCursorModel.legacySlugs??[],supportsThinking:ocxCursorStored?.supportsThinking??ocxCursorModel.supportsThinking}}),`;
+}
+
+export function patchCursorWorkbenchSource(source) {
+  if (source.includes(cursorPatchMarker)) return { status: "already-patched", source };
+  if (source.includes(legacyCursorPatchMarker) || source.includes("/*ocx-cursor-model-metadata-v2*/")) {
+    const matches = [...source.matchAll(previousCatalogInjection)];
+    if (matches.length !== 1) {
+      throw new Error(`Expected one legacy Cursor model metadata hook, found ${matches.length}`);
+    }
+    const match = matches[0];
+    const replacement = metadataInjection(match.groups.catalog);
+    return {
+      status: "patched",
+      source: `${source.slice(0, match.index)}${replacement}${source.slice(match.index + match[0].length)}`,
+    };
+  }
+  const matches = [...source.matchAll(catalogNormalization)];
+  if (matches.length !== 1) {
+    throw new Error(`Expected one Cursor model catalog storage hook, found ${matches.length}`);
+  }
+  const match = matches[0];
+  const { normalization, catalog } = match.groups;
+  const injection = `${normalization},${metadataInjection(catalog)}`;
+  const patched = `${source.slice(0, match.index)}${injection}${source.slice(match.index + match[0].length)}`;
+  return { status: "patched", source: patched };
+}
+
+export function patchCursorLocalModeSource(source) {
+  const disabledCount = source.split(cursorLocalModeDisabled).length - 1;
+  if (disabledCount > 1) {
+    throw new Error(`Expected at most one disabled Cursor localMode flag, found ${disabledCount}`);
+  }
+  if (disabledCount === 1) {
+    return {
+      status: "patched",
+      source: source.replace(cursorLocalModeDisabled, cursorLocalModeEnabled),
+    };
+  }
+  if (source.includes(cursorLocalModeEnabled)) return { status: "already-patched", source };
+  throw new Error("Cursor localMode build flag was not found");
+}
+
+export function patchCursorBundleSource(source, options = {}) {
+  const localMode = patchCursorLocalModeSource(source);
+  const metadata = options.preserveCatalogMetadata
+    ? patchCursorWorkbenchSource(localMode.source)
+    : { status: "already-patched", source: localMode.source };
+  return {
+    status: localMode.status === "patched" || metadata.status === "patched"
+      ? "patched"
+      : "already-patched",
+    source: metadata.source,
+  };
+}
+
+export function patchCursorLocalRuntimeSource(source) {
+  if (source.includes(cursorLocalRuntimePatchMarker)) return { status: "already-patched", source };
+  const matches = [...source.matchAll(localModelConstructor)];
+  if (matches.length !== 1) {
+    throw new Error(`Expected one Cursor local model constructor, found ${matches.length}`);
+  }
+  const match = matches[0];
+  const { functionName, modelType } = match.groups;
+  const replacement = `function ${functionName}(e,t){${cursorLocalRuntimePatchMarker}const ocxCursorDisplayWords={claude:"Claude",codex:"Codex",composer:"Composer",deepseek:"DeepSeek",fable:"Fable",fast:"Fast",flash:"Flash",gpt:"GPT",grok:"Grok",hy3:"HY3",kimi:"Kimi",luna:"Luna",max:"Max",mimo:"MiMo",mini:"Mini",opus:"Opus",pro:"Pro",qwen:"Qwen",sol:"Sol",sonnet:"Sonnet",spark:"Spark",terra:"Terra"};const ocxCursorDisplayName=null!=t?t:e.startsWith("opencodex/")?e.split("/").at(-1).split("-").map(ocxCursorWord=>{if(ocxCursorDisplayWords[ocxCursorWord])return ocxCursorDisplayWords[ocxCursorWord];const ocxCursorAttached=/^(qwen|kimi|gpt|claude|grok)(\\d+(?:\\.\\d+)*)$/.exec(ocxCursorWord);if(ocxCursorAttached)return ocxCursorDisplayWords[ocxCursorAttached[1]]+" "+ocxCursorAttached[2];if(/^v\\d/i.test(ocxCursorWord))return"V"+ocxCursorWord.slice(1);if(/^k\\d/i.test(ocxCursorWord))return"K"+ocxCursorWord.slice(1);if(/^\\d/.test(ocxCursorWord))return ocxCursorWord;return ocxCursorWord.slice(0,1).toUpperCase()+ocxCursorWord.slice(1)}).join(" "):e;return new ${modelType}({modelId:e,displayModelId:e,displayName:ocxCursorDisplayName,displayNameShort:ocxCursorDisplayName,aliases:[]})}`;
+  return {
+    status: "patched",
+    source: `${source.slice(0, match.index)}${replacement}${source.slice(match.index + match[0].length)}`,
+  };
+}
+
+export async function cursorWorkbenchSignature(file = cursorWorkbenchFile) {
+  const value = await stat(file);
+  return `${value.dev}:${value.ino}:${value.size}:${value.mtimeMs}`;
+}
+
+async function writePatchedFile(file, source, patched, backupDirectory) {
+  if (patched.status === "already-patched") {
+    return { status: patched.status, signature: await cursorWorkbenchSignature(file), backupPath: null };
+  }
+
+  await mkdir(backupDirectory, { recursive: true });
+  const digest = createHash("sha256").update(source).digest("hex").slice(0, 16);
+  const backupPath = join(backupDirectory, `${basename(file)}.${digest}.bak`);
+  await copyFile(file, backupPath);
+
+  const mode = (await stat(file)).mode & 0o777;
+  const temporary = `${file}.ocx-cursor-${process.pid}`;
+  await writeFile(temporary, patched.source, { mode });
+  await chmod(temporary, mode);
+  await rename(temporary, file);
+  return { status: patched.status, signature: await cursorWorkbenchSignature(file), backupPath };
+}
+
+export async function ensureCursorWorkbenchPatched(options = {}) {
+  const file = options.file || cursorWorkbenchFile;
+  const backupDirectory = options.backupDirectory || cursorPatchBackupDirectory;
+  const source = await readFile(file, "utf8");
+  const patched = patchCursorBundleSource(source, {
+    preserveCatalogMetadata: options.preserveCatalogMetadata ?? true,
+  });
+  return await writePatchedFile(file, source, patched, backupDirectory);
+}
+
+export async function ensureCursorLocalRuntimesPatched(options = {}) {
+  const files = options.files || cursorLocalRuntimeFiles;
+  const backupDirectory = options.backupDirectory || cursorPatchBackupDirectory;
+  return await Promise.all(files.map(async (file) => {
+    const source = await readFile(file, "utf8");
+    return {
+      file,
+      ...await writePatchedFile(file, source, patchCursorLocalRuntimeSource(source), backupDirectory),
+    };
+  }));
+}
+
+export async function ensureCursorBundlesPatched(options = {}) {
+  const files = options.files || cursorBundleFiles;
+  return await Promise.all(files.map(async (file) => ({
+    file,
+    ...await ensureCursorWorkbenchPatched({
+      ...options,
+      file,
+      preserveCatalogMetadata: isCursorModelMetadataBundle(file),
+    }),
+  })));
+}
+
+export async function ensureCursorAppPatched(options = {}) {
+  const [bundles, runtimes] = await Promise.all([
+    ensureCursorBundlesPatched({
+      ...options,
+      files: options.bundleFiles,
+    }),
+    ensureCursorLocalRuntimesPatched({
+      ...options,
+      files: options.localRuntimeFiles,
+    }),
+  ]);
+  return [...bundles, ...runtimes];
+}
+
+async function ensureCursorPatchFile(file, localRuntimeFiles, options) {
+  if (localRuntimeFiles.has(file)) {
+    const [result] = await ensureCursorLocalRuntimesPatched({
+      ...options,
+      files: [file],
+    });
+    return result;
+  }
+  return {
+    file,
+    ...await ensureCursorWorkbenchPatched({
+      ...options,
+      file,
+      preserveCatalogMetadata: options.file ? true : isCursorModelMetadataBundle(file),
+    }),
+  };
+}
+
+export function startCursorPatchMonitor(options = {}) {
+  const intervalMs = options.intervalMs || 250;
+  const bundleFiles = options.file ? [options.file] : (options.bundleFiles || options.files || cursorBundleFiles);
+  const runtimeFiles = options.file ? [] : (options.localRuntimeFiles || cursorLocalRuntimeFiles);
+  const files = [...bundleFiles, ...runtimeFiles];
+  const localRuntimeFiles = new Set(runtimeFiles);
+  const lastSignatures = new Map();
+  let patchPromise = null;
+  let stopped = false;
+
+  const check = async () => {
+    if (stopped || patchPromise || options.shouldPatch?.() === false) return patchPromise;
+    patchPromise = Promise.all(files.map(async (file) => {
+      let signature;
+      try {
+        signature = await cursorWorkbenchSignature(file);
+      } catch {
+        return;
+      }
+      if (signature === lastSignatures.get(file)) return;
+      try {
+        const result = await ensureCursorPatchFile(file, localRuntimeFiles, options);
+        lastSignatures.set(file, result.signature);
+        options.onResult?.(result);
+      } catch (error) {
+        if (!transientPatchErrorCodes.has(error.code)) lastSignatures.set(file, signature);
+        options.onError?.(error, file);
+      }
+    })).finally(() => {
+      patchPromise = null;
+    });
+    return patchPromise;
+  };
+
+  const timer = setInterval(check, intervalMs);
+  void check();
+  return {
+    check,
+    stop() {
+      stopped = true;
+      clearInterval(timer);
+    },
+  };
+}

package/src/cursor-state.mjs

@@ -5,6 +5,45 @@ import { effortLabels } from "./catalog.mjs";
 import { cursorDatabaseFile, installRoot, managedPrefix, pendingFile } from "./paths.mjs";
 
 const storageKey = "src.vs.platform.reactivestorage.browser.reactiveStorageServiceImpl.persistentStorage.applicationUser";
+const displayWords = new Map([
+  ["claude", "Claude"],
+  ["codex", "Codex"],
+  ["composer", "Composer"],
+  ["deepseek", "DeepSeek"],
+  ["fable", "Fable"],
+  ["fast", "Fast"],
+  ["flash", "Flash"],
+  ["gpt", "GPT"],
+  ["grok", "Grok"],
+  ["hy3", "HY3"],
+  ["kimi", "Kimi"],
+  ["luna", "Luna"],
+  ["max", "Max"],
+  ["mimo", "MiMo"],
+  ["mini", "Mini"],
+  ["opus", "Opus"],
+  ["pro", "Pro"],
+  ["qwen", "Qwen"],
+  ["sol", "Sol"],
+  ["sonnet", "Sonnet"],
+  ["spark", "Spark"],
+  ["terra", "Terra"],
+]);
+
+function displayWord(value) {
+  const known = displayWords.get(value);
+  if (known) return known;
+  const attachedVersion = /^(qwen|kimi|gpt|claude|grok)(\d+(?:\.\d+)*)$/.exec(value);
+  if (attachedVersion) return `${displayWords.get(attachedVersion[1])} ${attachedVersion[2]}`;
+  if (/^v\d/i.test(value)) return `V${value.slice(1)}`;
+  if (/^k\d/i.test(value)) return `K${value.slice(1)}`;
+  if (/^\d/.test(value)) return value;
+  return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+}
+
+export function displayNameFor(model) {
+  return model.sourceId.split("/").at(-1).split("-").map(displayWord).join(" ");
+}
 
 export function cursorIsRunning() {
   try {
@@ -62,13 +101,14 @@ function fastDefinition() {
 function modelVariants(model) {
   const parameterId = parameterIdFor(model);
   const selectedDefault = defaultEffort(model);
+  const modelDisplayName = displayNameFor(model);
   const efforts = model.reasoningEfforts.length > 0 ? model.reasoningEfforts : [null];
   const fastValues = model.supportsFast ? ["false", "true"] : [null];
   return efforts.flatMap((effort) => fastValues.map((fast) => {
     const labels = [effort ? effortLabels[effort] : null, fast === "true" ? "Fast" : null].filter(Boolean);
     const displayName = labels.length > 0
-      ? `${model.alias} <span style="color: var(--cursor-text-tertiary);">${labels.join(" ")}</span>`
-      : model.alias;
+      ? `${modelDisplayName} <span style="color: var(--cursor-text-tertiary);">${labels.join(" ")}</span>`
+      : modelDisplayName;
     const isDefault = (effort === null || effort === selectedDefault) && fast !== "true";
     const parameters = [
       ...(effort ? [{ id: parameterId, value: effort }] : []),
@@ -91,8 +131,10 @@ export function cursorModel(model) {
   const hasEffort = model.reasoningEfforts.length > 0;
   const hasVariants = hasEffort || model.supportsFast;
   const variants = hasVariants ? modelVariants(model) : [];
+  const displayName = displayNameFor(model);
   return {
     name: model.alias,
+    clientDisplayName: displayName,
     defaultOn: false,
     supportsAgent: true,
     degradationStatus: 0,
@@ -105,7 +147,7 @@ export function cursorModel(model) {
     supportsPlanMode: true,
     supportsSandboxing: true,
     isUserAdded: true,
-    inputboxShortModelName: model.alias,
+    inputboxShortModelName: displayName,
     idAliases: [],
     namedModelSectionIndex: 1,
     cloudAgentEffortModes: [],

package/src/gateway.mjs

@@ -36,6 +36,15 @@ function suppliedFast(variantText) {
     .find(([key]) => key === "fast")?.[1];
 }
 
+function disableStrictFunctionTools(tools) {
+  if (!Array.isArray(tools)) return;
+  for (const tool of tools) {
+    if (!isRecord(tool) || tool.type !== "function") continue;
+    const definition = isRecord(tool.function) ? tool.function : tool;
+    if (definition.strict === true) definition.strict = false;
+  }
+}
+
 export function rewriteModelAliasBody(body, catalog) {
   if (!body?.length) return body;
   let payload;
@@ -71,6 +80,7 @@ export function rewriteModelAliasBody(body, catalog) {
   if (catalogModel?.supportsFast && fast === "true") payload.service_tier = "priority";
   if (catalogModel?.supportsFast && fast === "false") delete payload.service_tier;
   delete payload.reasoningEffort;
+  disableStrictFunctionTools(payload.tools);
   return Buffer.from(JSON.stringify(payload));
 }
 

package/src/install.mjs

@@ -4,6 +4,8 @@ import { access, chmod, copyFile, cp, lstat, mkdir, mkdtemp, readFile, readlink,
 import { tmpdir } from "node:os";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { ensureCursorAppPatched } from "./cursor-patch.mjs";
+import { cursorIsRunning } from "./cursor-state.mjs";
 import {
   cliLinkFile,
   installRoot,
@@ -165,6 +167,7 @@ function launchAgent(nodePath) {
 export async function installService() {
   await mkdir(dirname(launchAgentFile), { recursive: true });
   const { legacyPlist, secretStatus } = await prepareInstallSecret();
+  const cursorPatches = cursorIsRunning() ? null : await ensureCursorAppPatched();
   await copyPackage();
   await installCliLink();
 
@@ -179,7 +182,7 @@ export async function installService() {
     await rm(disabled, { force: true });
     await rename(legacyPlist, disabled);
   }
-  return { installRoot, launchAgentFile, cliLinkFile, secretStatus };
+  return { installRoot, launchAgentFile, cliLinkFile, secretStatus, cursorPatches };
 }
 
 export async function updateService(options = {}) {

package/src/paths.mjs

@@ -14,6 +14,24 @@ export const stderrFile = join(installRoot, "service.error.log");
 export const launchAgentFile = join(homedir(), "Library", "LaunchAgents", `${serviceLabel}.plist`);
 export const legacyLaunchAgentFile = join(homedir(), "Library", "LaunchAgents", `${legacyServiceLabel}.plist`);
 export const cursorDatabaseFile = join(homedir(), "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb");
+export const cursorAppOutDirectory = "/Applications/Cursor.app/Contents/Resources/app/out";
+export const cursorWorkbenchFile = join(cursorAppOutDirectory, "vs", "workbench", "workbench.desktop.main.js");
+export const cursorGlassWorkbenchFile = join(cursorAppOutDirectory, "vs", "workbench", "workbench.glass.main.js");
+export const cursorLocalRuntimeFiles = [
+  "/Applications/Cursor.app/Contents/Resources/app/extensions/cursor-local-agent-runtime/dist/main.js",
+  "/Applications/Cursor.app/Contents/Resources/app/extensions/cursor-agent-exec/dist/main.js",
+];
+export const cursorBundleFiles = [
+  join(cursorAppOutDirectory, "main.js"),
+  join(cursorAppOutDirectory, "vs", "code", "electron-utility", "alwaysLocalSingleton", "alwaysLocalSingletonMain.js"),
+  join(cursorAppOutDirectory, "vs", "code", "electron-utility", "mcpProcess", "mcpProcessMain.js"),
+  join(cursorAppOutDirectory, "vs", "code", "electron-utility", "sharedProcess", "sharedProcessMain.js"),
+  join(cursorAppOutDirectory, "vs", "workbench", "api", "node", "extensionHostProcess.js"),
+  join(cursorAppOutDirectory, "vs", "workbench", "api", "worker", "extensionHostWorkerMain.js"),
+  cursorWorkbenchFile,
+  cursorGlassWorkbenchFile,
+];
+export const cursorPatchBackupDirectory = join(installRoot, "cursor-app-backups");
 export const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
 export const codexConfigFile = join(codexHome, "config.toml");
 export const defaultCodexCatalogFile = join(codexHome, "opencodex-catalog.json");
@@ -21,5 +39,6 @@ export const opencodexConfigFile = join(homedir(), ".opencodex", "config.json");
 export const opencodexServiceTokenFile = join(homedir(), ".opencodex", "service-api-token");
 export const gatewayPort = Number(process.env.OCX_CURSOR_PORT || "10101");
 export const gatewayHost = process.env.OCX_CURSOR_HOST || "127.0.0.1";
+export const cursorLocalBaseUrl = `http://127.0.0.1:${gatewayPort}/v1`;
 export const cursorOpenAIBaseUrl = process.env.OCX_CURSOR_BASE_URL || "";
 export const managedPrefix = "opencodex/";

package/src/service.mjs

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { buildActiveCatalog } from "./catalog.mjs";
+import { startCursorPatchMonitor } from "./cursor-patch.mjs";
 import {
   cursorIsRunning,
   readPendingCatalog,
@@ -58,6 +59,14 @@ export async function runService(options = {}) {
   }
 
   const server = startGateway({ secret, getCatalog: () => catalog, host: options.host, port: options.port });
+  const patchMonitor = startCursorPatchMonitor({
+    intervalMs: options.cursorPatchIntervalMs,
+    shouldPatch: () => !cursorIsRunning(),
+    onResult: (result) => {
+      if (result.status === "patched") process.stdout.write(`Patched Cursor app file ${result.file} (backup: ${result.backupPath})\n`);
+    },
+    onError: (error, file) => process.stderr.write(`Cursor patch failed for ${file}: ${error.message}\n`),
+  });
   const refreshTimer = setInterval(refresh, options.refreshIntervalMs || 15_000);
   const pendingTimer = setInterval(() => {
     if (cursorSyncPromise) return;
@@ -85,6 +94,7 @@ export async function runService(options = {}) {
     stopped = true;
     clearInterval(refreshTimer);
     clearInterval(pendingTimer);
+    patchMonitor.stop();
     server.close(() => process.exit(0));
   };
   process.on("SIGTERM", stop);

package/src/setup.mjs

@@ -1,24 +1,33 @@
 export function normalizeBaseUrl(value) {
   if (!value) {
-    throw new Error("Enter your Cloudflare Tunnel URL or pass --base-url https://your-domain.example/v1");
+    throw new Error("Enter an endpoint URL or pass --base-url http://127.0.0.1:10101/v1");
   }
 
-  const candidate = value.includes("://") ? value : `https://${value}`;
+  const trimmed = value.trim();
+  const loopbackWithoutScheme = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])(?::|\/|$)/i.test(trimmed);
+  const candidate = trimmed.includes("://")
+    ? trimmed
+    : `${loopbackWithoutScheme ? "http" : "https"}://${trimmed}`;
   let url;
   try {
     url = new URL(candidate);
   } catch {
-    throw new Error(`Invalid Cloudflare Tunnel URL: ${value}`);
+    throw new Error(`Invalid endpoint URL: ${value}`);
   }
 
-  if (url.protocol !== "https:") throw new Error("Cloudflare Tunnel URL must use HTTPS");
+  const isLoopback = url.hostname === "localhost"
+    || url.hostname === "[::1]"
+    || /^127(?:\.\d{1,3}){3}$/.test(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback)) {
+    throw new Error("Endpoint URL must use HTTPS unless it points to localhost");
+  }
   if (url.username || url.password || url.search || url.hash) {
-    throw new Error("Cloudflare Tunnel URL cannot contain credentials, a query, or a fragment");
+    throw new Error("Endpoint URL cannot contain credentials, a query, or a fragment");
   }
 
   const pathname = url.pathname.replace(/\/+$/, "");
   if (pathname && pathname !== "/v1") {
-    throw new Error("Cloudflare Tunnel URL must be a hostname or end with /v1");
+    throw new Error("Endpoint URL must be an origin or end with /v1");
   }
   url.pathname = "/v1";
   return url.toString().replace(/\/$/, "");
@@ -43,7 +52,7 @@ async function checkedJson(fetchImpl, url, options, label) {
   }
 }
 
-export async function testTunnel(baseUrl, secret, options = {}) {
+export async function testEndpoint(baseUrl, secret, options = {}) {
   baseUrl = normalizeBaseUrl(baseUrl);
   const fetchImpl = options.fetchImpl || fetch;
   const origin = new URL(baseUrl).origin;
@@ -52,7 +61,7 @@ export async function testTunnel(baseUrl, secret, options = {}) {
   let healthError;
   for (let attempt = 0; attempt < attempts; attempt += 1) {
     try {
-      health = await checkedJson(fetchImpl, `${origin}/healthz`, {}, "Tunnel health check");
+      health = await checkedJson(fetchImpl, `${origin}/healthz`, {}, "Endpoint health check");
       break;
     } catch (error) {
       healthError = error;
@@ -63,14 +72,14 @@ export async function testTunnel(baseUrl, secret, options = {}) {
   }
   if (!health) throw healthError;
   if (health?.service !== "opencodex-cursor-bridge" || health?.status !== "ok") {
-    throw new Error(`Tunnel health check reached an unexpected service at ${origin}/healthz`);
+    throw new Error(`Endpoint health check reached an unexpected service at ${origin}/healthz`);
   }
 
   const models = await checkedJson(fetchImpl, `${baseUrl}/models`, {
     headers: { authorization: `Bearer ${secret}` },
-  }, "Tunnel model check");
+  }, "Endpoint model check");
   if (!Array.isArray(models?.data)) {
-    throw new Error(`Tunnel model check returned an invalid catalog from ${baseUrl}/models`);
+    throw new Error(`Endpoint model check returned an invalid catalog from ${baseUrl}/models`);
   }
 
   return { health, modelCount: models.data.length };