ocx-cursor 0.1.0 → 0.3.0

package/README.md

@@ -3,27 +3,101 @@
 [![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 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 local gateway, registers the endpoint 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
-- OpenCodex installed, signed in, and running
-- An HTTPS hostname that forwards to `http://127.0.0.1:10101`
+- A domain using Cloudflare DNS, or another HTTPS reverse proxy
 
 Launch Cursor and sign in once before setup. Cursor creates the Safe Storage key that the installer uses to encrypt the gateway API key.
 
-## Set up an HTTPS endpoint
+## Setup
 
-Cursor's custom OpenAI endpoint must use HTTPS. Point a tunnel or reverse proxy at the local gateway on port `10101`.
+The commands below use `cursor-api.example.com`. Replace it with a hostname under your own Cloudflare-managed domain.
 
-This Cloudflare Tunnel config maps `cursor-api.example.com` to the gateway:
+### 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.
+
+Install OpenCodex without `sudo` from a user-owned Node.js installation:
+
+```bash
+npm install --global @bitkyc08/opencodex
+ocx init
+```
+
+The bridge service looks for `ocx` at `~/.local/bin/ocx` and `/opt/homebrew/bin/ocx`. If `command -v ocx` prints another path, link it into `~/.local/bin`:
+
+```bash
+mkdir -p ~/.local/bin
+if [[ "$(command -v ocx)" != "$HOME/.local/bin/ocx" ]]; then
+  ln -sf "$(command -v ocx)" ~/.local/bin/ocx
+fi
+```
+
+`ocx init` opens the interactive provider setup. You can also open the dashboard and add or sign in to a provider there:
+
+```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:
+
+```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:
+
+```bash
+curl \
+  --header "Authorization: Bearer $(cat ~/.opencodex/service-api-token)" \
+  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:
+
+```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_ID
-credentials-file: /Users/YOU/.cloudflared/YOUR_TUNNEL_ID.json
+tunnel: YOUR_TUNNEL_UUID
+credentials-file: /Users/YOUR_MACOS_USERNAME/.cloudflared/YOUR_TUNNEL_UUID.json
 
 ingress:
   - hostname: cursor-api.example.com
@@ -31,18 +105,54 @@ ingress:
   - service: http_status:404
 ```
 
-Create the DNS route and run the tunnel:
+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 tunnel route dns YOUR_TUNNEL_NAME cursor-api.example.com
-cloudflared tunnel run YOUR_TUNNEL_NAME
+cloudflared service install
 ```
 
-The package does not install or manage the tunnel.
+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.
 
-## Install
+### 3. Install the Cursor bridge
 
-Quit Cursor, confirm that OpenCodex is running, then run:
+Quit Cursor completely, confirm that OpenCodex is running, then initialize the bridge:
+
+```bash
+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 \
@@ -52,10 +162,11 @@ npx ocx-cursor init \
 `init` performs these actions:
 
 1. Generates a gateway API key in `~/.opencodex/cursor-bridge/secret`.
-2. Stores the key in Cursor with macOS Safe Storage encryption.
-3. Registers the HTTPS URL as Cursor's OpenAI base URL.
-4. Installs the `com.opencodex.cursor-bridge` LaunchAgent.
-5. Adds active OpenCodex models to Cursor under `opencodex/*`.
+2. Installs the `com.opencodex.cursor-bridge` LaunchAgent.
+3. Tests the Cloudflare Tunnel 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.
+6. Adds active OpenCodex models to Cursor under `opencodex/*`.
 
 The installer links `ocx-cursor` into `~/.local/bin`. Add that directory to `PATH` if your shell does not include it:
 
@@ -63,20 +174,51 @@ The installer links `ocx-cursor` into `~/.local/bin`. Add that directory to `PAT
 export PATH="$HOME/.local/bin:$PATH"
 ```
 
-Open Cursor after `init` finishes. Models with known reasoning controls show an effort value in the picker. Use `Shift+Command+/` to cycle it.
+Check the local gateway and public hostname before opening Cursor:
+
+```bash
+ocx-cursor status
+curl https://cursor-api.example.com/healthz
+```
+
+The status output should show `Service: running` and `Gateway: healthy`. The public health endpoint should return JSON with `"status":"ok"`.
+
+Open Cursor after both checks pass. Models with known reasoning controls show an effort value in the picker. Use `Shift+Command+/` to cycle it.
+
+### Fast mode
+
+OpenAI models whose OpenCodex catalog advertises the `priority` service tier show a Fast toggle in Cursor. Fast is off by default. When enabled, the bridge sends `service_tier: "priority"` to OpenCodex, which increases generation speed and consumes more usage.
+
+Fast requires an OpenCodex version that preserves `service_tier` on its Chat Completions compatibility endpoint. Models without the `priority` tier, including Anthropic subscription models, do not receive the toggle.
+
+## How requests are routed
+
+```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
+  -> 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.
 
 ## Commands
 
 | Command | Purpose |
 | --- | --- |
-| `ocx-cursor init --base-url URL` | Configure Cursor, install the service, and sync models. Cursor must be closed. |
+| `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 sync` | Refresh the active model catalog. The service queues the update while Cursor runs. |
 | `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.
 
+`update` preserves the existing gateway API key and Cursor endpoint. It updates only this companion package; update OpenCodex separately with your package manager.
+
 ## Model mapping
 
 The bridge maps source model IDs to Cursor aliases:
@@ -94,7 +236,7 @@ Cursor removes custom effort metadata from its database during startup. The Laun
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
-| `OCX_CURSOR_BASE_URL` | Stored Cursor URL | HTTPS endpoint used by `init` when `--base-url` is absent. |
+| `OCX_CURSOR_BASE_URL` | Stored Cursor URL | Prompt default, or endpoint for non-interactive `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. |
@@ -109,6 +251,70 @@ The gateway accepts these routes:
 
 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
+
+The tunnel is running, but it cannot reach the local bridge. Check the bridge and its logs:
+
+```bash
+ocx-cursor status
+tail -n 100 ~/.opencodex/cursor-bridge/service.error.log
+tail -n 100 ~/.opencodex/cursor-bridge/service.log
+```
+
+Confirm that the tunnel ingress points to `http://127.0.0.1:10101`, then restart the bridge if needed:
+
+```bash
+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
+```
+
+If you installed the login service, inspect it with:
+
+```bash
+launchctl print "gui/$(id -u)/com.cloudflare.cloudflared"
+```
+
+### 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
+```
+
+### Models or effort options are missing
+
+Cursor must be closed before its local model database can be changed. Quit Cursor and run:
+
+```bash
+ocx-cursor sync
+ocx-cursor status
+```
+
+If the status shows a pending sync, wait until every Cursor Helper process has exited. The service applies the queued catalog automatically.
+
+### OpenCodex models cannot be loaded
+
+Check OpenCodex first:
+
+```bash
+ocx status
+ocx models --json
+curl http://127.0.0.1:10100/v1/models
+```
+
+If `ocx models --json` works in your shell but fails in the bridge, check that `ocx` is available at `~/.local/bin/ocx` or `/opt/homebrew/bin/ocx`. The macOS LaunchAgent does not load your interactive shell profile.
+
 ## Development
 
 ```bash

package/bin/ocx-cursor.mjs

@@ -2,19 +2,23 @@
 
 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 { cursorIsRunning } from "../src/cursor-state.mjs";
-import { installService, prepareInstallSecret, serviceStatus, uninstallService } from "../src/install.mjs";
+import { installService, prepareInstallSecret, serviceStatus, uninstallService, updateService } from "../src/install.mjs";
 import { cursorOpenAIBaseUrl, pendingFile } from "../src/paths.mjs";
 import { runService } from "../src/service.mjs";
+import { normalizeBaseUrl, testTunnel } from "../src/setup.mjs";
 import { loadCatalogSnapshot, syncNow } from "../src/sync.mjs";
 
 const usage = `OpenCodex Cursor Bridge
 
 Usage:
-  ocx-cursor init --base-url <https-url>
-                        Configure Cursor, install the service, and sync models
+  ocx-cursor init [--base-url <https-url>]
+                        Install the service, test the tunnel, 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
   ocx-cursor sync       Sync active OpenCodex models into Cursor
   ocx-cursor status     Show service and model-sync status
   ocx-cursor uninstall  Stop and remove the companion service
@@ -26,20 +30,21 @@ function argumentValue(name) {
   return index === -1 ? "" : String(process.argv[index + 1] || "");
 }
 
-function normalizedBaseUrl(value) {
-  if (!value) {
-    throw new Error("Pass --base-url https://your-domain.example/v1 or set OCX_CURSOR_BASE_URL");
-  }
-  let url;
+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 {
-    url = new URL(value);
-  } catch {
-    throw new Error(`Invalid Cursor OpenAI base URL: ${value}`);
+    return normalizeBaseUrl((await readline.question(prompt)).trim() || fallback);
+  } finally {
+    readline.close();
   }
-  if (url.protocol !== "https:") throw new Error("Cursor OpenAI base URL must use HTTPS");
-  url.pathname = url.pathname.replace(/\/$/, "");
-  if (!url.pathname.endsWith("/v1")) throw new Error("Cursor OpenAI base URL must end with /v1");
-  return url.toString().replace(/\/$/, "");
 }
 
 async function pendingCount() {
@@ -83,10 +88,18 @@ async function main() {
     if (cursorIsRunning()) {
       throw new Error("Quit Cursor before running ocx-cursor init so model variants and effort selectors can be applied");
     }
-    const baseUrl = normalizedBaseUrl(
-      argumentValue("--base-url") || cursorOpenAIBaseUrl || storedCursorOpenAIBaseUrl(),
-    );
+    const baseUrl = await requestedBaseUrl();
     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;
+    try {
+      tunnel = await testTunnel(baseUrl, prepared.secret);
+    } catch (error) {
+      throw new Error(`${error.message}\nThe bridge service is running locally. Fix the tunnel and rerun ocx-cursor init.`);
+    }
+    process.stdout.write(`Tunnel is ready (${tunnel.modelCount} models reachable).\n`);
     const configured = await configureCursorOpenAI({
       secret: prepared.secret,
       baseUrl,
@@ -94,11 +107,14 @@ async function main() {
     process.stdout.write(configured.changed
       ? `Configured Cursor OpenAI endpoint: ${baseUrl}\nBackup: ${configured.backupPath}\n`
       : `Cursor OpenAI endpoint is already configured: ${baseUrl}\n`);
-    const installed = await installService();
-    process.stdout.write(`Installed ${installed.launchAgentFile} (API key ${installed.secretStatus}).\nCLI: ${installed.cliLinkFile}\n`);
     printSync(await syncNow());
     return;
   }
+  if (command === "update") {
+    process.stdout.write("Updating OpenCodex Cursor Bridge from npm...\n");
+    updateService();
+    return;
+  }
   if (command === "sync") {
     printSync(await syncNow());
     return;

package/package.json

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

package/src/catalog.mjs

@@ -1,8 +1,15 @@
 import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
-import { managedPrefix, opencodexConfigFile, opencodexServiceTokenFile } from "./paths.mjs";
+import { dirname, join, resolve } from "node:path";
+import {
+  codexConfigFile,
+  defaultCodexCatalogFile,
+  managedPrefix,
+  opencodexConfigFile,
+  opencodexServiceTokenFile,
+} from "./paths.mjs";
 
 export const allowedEfforts = ["low", "medium", "high", "xhigh", "max"];
 export const effortLabels = {
@@ -44,7 +51,29 @@ export function sanitizeEfforts(sourceId, configured) {
   return allowedEfforts.filter((effort) => values.includes(effort));
 }
 
-export function normalizeActiveCatalog(configured, active) {
+export function configuredCodexCatalogFile(configFile = codexConfigFile) {
+  try {
+    const content = readFileSync(configFile, "utf8");
+    const match = content.match(/^\s*model_catalog_json\s*=\s*("(?:[^"\\]|\\.)*")\s*$/m);
+    if (match) return resolve(dirname(configFile), JSON.parse(match[1]));
+  } catch {}
+  return defaultCodexCatalogFile;
+}
+
+export function priorityModelIds(catalogFile = configuredCodexCatalogFile()) {
+  try {
+    const payload = JSON.parse(readFileSync(catalogFile, "utf8"));
+    return new Set(payload.models
+      .filter((model) => Array.isArray(model?.service_tiers)
+        && model.service_tiers.some((tier) => tier?.id === "priority"))
+      .map((model) => model.slug || model.id)
+      .filter((id) => typeof id === "string"));
+  } catch {
+    return new Set();
+  }
+}
+
+export function normalizeActiveCatalog(configured, active, fastModelIds = new Set()) {
   const configuredById = new Map(configured
     .filter((model) => typeof model.provider === "string" && typeof model.model === "string")
     .map((model) => [`${model.provider}/${model.model}`, model]));
@@ -69,6 +98,7 @@ export function normalizeActiveCatalog(configured, active) {
       maxOutputTokens: model.capabilities?.max_output_tokens,
       inputModalities,
       reasoningEfforts: sanitizeEfforts(model.id, configuredModel?.reasoningEfforts ?? model.capabilities?.reasoning_effort),
+      supportsFast: fastModelIds.has(model.id),
     });
   }
 
@@ -113,5 +143,6 @@ export async function buildActiveCatalog(options = {}) {
   return normalizeActiveCatalog(
     configuredModels(options.ocxBin),
     await activeModels(options.fetchImpl),
+    options.fastModelIds || priorityModelIds(options.codexCatalogFile),
   );
 }

package/src/cursor-state.mjs

@@ -42,26 +42,55 @@ function effortDefinition(model) {
   };
 }
 
-function effortVariants(model) {
+function fastDefinition() {
+  return {
+    id: "fast",
+    name: "Fast",
+    markdownTooltip: "1.5x speed with increased usage.",
+    parameterType: {
+      booleanParameter: {
+        values: [
+          { value: "false" },
+          { value: "true", displayName: "Fast", increasesModelCost: true },
+        ],
+      },
+    },
+    isCycleableByHotkey: false,
+  };
+}
+
+function modelVariants(model) {
   const parameterId = parameterIdFor(model);
   const selectedDefault = defaultEffort(model);
-  return model.reasoningEfforts.map((effort) => {
-    const displayName = `${model.alias} <span style="color: var(--cursor-text-tertiary);">${effortLabels[effort]}</span>`;
-    const isDefault = effort === selectedDefault;
+  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;
+    const isDefault = (effort === null || effort === selectedDefault) && fast !== "true";
+    const parameters = [
+      ...(effort ? [{ id: parameterId, value: effort }] : []),
+      ...(fast ? [{ id: "fast", value: fast }] : []),
+    ];
+    const suffix = [effort, fast === "true" ? "fast" : null].filter(Boolean).join("-");
     return {
-      parameterValues: [{ id: parameterId, value: effort }],
+      parameterValues: parameters,
       displayName,
       displayNameOutsidePicker: displayName,
       isMaxMode: false,
       ...(isDefault ? { isDefaultMaxConfig: true, isDefaultNonMaxConfig: true } : {}),
-      variantStringRepresentation: `${model.alias}[${parameterId}=${effort}]`,
-      legacySlug: `${model.alias}-${effort}`,
+      variantStringRepresentation: `${model.alias}[${parameters.map(({ id, value }) => `${id}=${value}`).join(",")}]`,
+      legacySlug: suffix ? `${model.alias}-${suffix}` : model.alias,
     };
-  });
+  }));
 }
 
 export function cursorModel(model) {
   const hasEffort = model.reasoningEfforts.length > 0;
+  const hasVariants = hasEffort || model.supportsFast;
+  const variants = hasVariants ? modelVariants(model) : [];
   return {
     name: model.alias,
     defaultOn: false,
@@ -80,9 +109,12 @@ export function cursorModel(model) {
     idAliases: [],
     namedModelSectionIndex: 1,
     cloudAgentEffortModes: [],
-    parameterDefinitions: hasEffort ? [effortDefinition(model)] : [],
-    variants: hasEffort ? effortVariants(model) : [],
-    legacySlugs: model.reasoningEfforts.map((effort) => `${model.alias}-${effort}`),
+    parameterDefinitions: [
+      ...(hasEffort ? [effortDefinition(model)] : []),
+      ...(model.supportsFast ? [fastDefinition()] : []),
+    ],
+    variants,
+    legacySlugs: variants.map(({ legacySlug }) => legacySlug),
     modelPickerBadges: [],
   };
 }
@@ -93,15 +125,18 @@ function syncSelectedModel(state, catalog) {
   const byAlias = new Map(catalog.map((model) => [model.alias, model]));
   for (const selected of composer.selectedModels) {
     const model = byAlias.get(selected.modelId);
-    if (!model || model.reasoningEfforts.length === 0) continue;
+    if (!model || (model.reasoningEfforts.length === 0 && !model.supportsFast)) continue;
     const parameterId = parameterIdFor(model);
-    const current = Array.isArray(selected.parameters)
-      ? selected.parameters.find(({ id }) => id === parameterId)?.value
-      : undefined;
-    selected.parameters = [{
-      id: parameterId,
-      value: model.reasoningEfforts.includes(current) ? current : defaultEffort(model),
-    }];
+    const current = Array.isArray(selected.parameters) ? selected.parameters : [];
+    const effort = current.find(({ id }) => id === parameterId)?.value;
+    const fast = current.find(({ id }) => id === "fast")?.value;
+    selected.parameters = [
+      ...(model.reasoningEfforts.length > 0 ? [{
+        id: parameterId,
+        value: model.reasoningEfforts.includes(effort) ? effort : defaultEffort(model),
+      }] : []),
+      ...(model.supportsFast ? [{ id: "fast", value: fast === "true" ? "true" : "false" }] : []),
+    ];
   }
 }
 

package/src/gateway.mjs

@@ -29,6 +29,13 @@ function suppliedEffort(payload, variantText) {
     || payload.reasoningEffort;
 }
 
+function suppliedFast(variantText) {
+  return variantText
+    ?.split(",")
+    .map((value) => value.split("=", 2))
+    .find(([key]) => key === "fast")?.[1];
+}
+
 export function rewriteModelAliasBody(body, catalog) {
   if (!body?.length) return body;
   let payload;
@@ -42,10 +49,16 @@ export function rewriteModelAliasBody(body, catalog) {
   const variant = /^(opencodex\/.+?)\[([^\]]+)\]$/.exec(payload.model);
   let alias = variant?.[1] || payload.model;
   let effort = suppliedEffort(payload, variant?.[2]);
+  let fast = suppliedFast(variant?.[2]);
   if (!allowedEfforts.includes(effort)) {
-    const legacy = catalog.find((model) => model.reasoningEfforts?.some((value) => payload.model === `${model.alias}-${value}`));
+    const legacy = catalog.find((model) => model.reasoningEfforts?.some((value) => (
+      payload.model === `${model.alias}-${value}` || payload.model === `${model.alias}-${value}-fast`
+    )));
     if (legacy) {
-      effort = legacy.reasoningEfforts.find((value) => payload.model === `${legacy.alias}-${value}`);
+      effort = legacy.reasoningEfforts.find((value) => (
+        payload.model === `${legacy.alias}-${value}` || payload.model === `${legacy.alias}-${value}-fast`
+      ));
+      fast = payload.model.endsWith("-fast") ? "true" : "false";
       alias = legacy.alias;
     }
   }
@@ -55,6 +68,8 @@ export function rewriteModelAliasBody(body, catalog) {
   payload.model = catalogModel?.sourceId
     || (fallbackSourceId.startsWith("claude-") ? `anthropic/${fallbackSourceId}` : fallbackSourceId);
   if (allowedEfforts.includes(effort)) payload.reasoning_effort = effort;
+  if (catalogModel?.supportsFast && fast === "true") payload.service_tier = "priority";
+  if (catalogModel?.supportsFast && fast === "false") delete payload.service_tier;
   delete payload.reasoningEffort;
   return Buffer.from(JSON.stringify(payload));
 }
@@ -77,6 +92,7 @@ export function enrichModelList(active, catalog) {
         supports_tool_use: true,
         supports_streaming: true,
         supports_reasoning: model.reasoningEfforts.length > 0,
+        supports_fast: model.supportsFast,
         supports_vision: model.inputModalities.includes("image"),
         reasoning_effort: model.reasoningEfforts,
       },

package/src/install.mjs

@@ -176,6 +176,18 @@ export async function installService() {
   return { installRoot, launchAgentFile, cliLinkFile, secretStatus };
 }
 
+export function updateService(options = {}) {
+  const execute = options.execFileSync || execFileSync;
+  execute(options.npmCommand || "npm", [
+    "exec",
+    "--yes",
+    "--package=ocx-cursor@latest",
+    "--",
+    "ocx-cursor",
+    "install",
+  ], { stdio: "inherit" });
+}
+
 export async function uninstallService() {
   bootout(serviceLabel);
   await rm(launchAgentFile, { force: true });

package/src/paths.mjs

@@ -14,6 +14,9 @@ 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 codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+export const codexConfigFile = join(codexHome, "config.toml");
+export const defaultCodexCatalogFile = join(codexHome, "opencodex-catalog.json");
 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");

package/src/setup.mjs

@@ -0,0 +1,77 @@
+export function normalizeBaseUrl(value) {
+  if (!value) {
+    throw new Error("Enter your Cloudflare Tunnel URL or pass --base-url https://your-domain.example/v1");
+  }
+
+  const candidate = value.includes("://") ? value : `https://${value}`;
+  let url;
+  try {
+    url = new URL(candidate);
+  } catch {
+    throw new Error(`Invalid Cloudflare Tunnel URL: ${value}`);
+  }
+
+  if (url.protocol !== "https:") throw new Error("Cloudflare Tunnel URL must use HTTPS");
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error("Cloudflare Tunnel 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");
+  }
+  url.pathname = "/v1";
+  return url.toString().replace(/\/$/, "");
+}
+
+async function checkedJson(fetchImpl, url, options, label) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      ...options,
+      signal: options?.signal || AbortSignal.timeout(10_000),
+    });
+  } catch (error) {
+    throw new Error(`${label} failed for ${url}: ${error.message}`);
+  }
+
+  if (!response.ok) throw new Error(`${label} returned HTTP ${response.status} for ${url}`);
+  try {
+    return await response.json();
+  } catch {
+    throw new Error(`${label} returned invalid JSON from ${url}`);
+  }
+}
+
+export async function testTunnel(baseUrl, secret, options = {}) {
+  baseUrl = normalizeBaseUrl(baseUrl);
+  const fetchImpl = options.fetchImpl || fetch;
+  const origin = new URL(baseUrl).origin;
+  const attempts = options.healthAttempts || 10;
+  let health;
+  let healthError;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      health = await checkedJson(fetchImpl, `${origin}/healthz`, {}, "Tunnel health check");
+      break;
+    } catch (error) {
+      healthError = error;
+      if (attempt + 1 < attempts) {
+        await new Promise((resolve) => setTimeout(resolve, options.retryDelayMs ?? 500));
+      }
+    }
+  }
+  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`);
+  }
+
+  const models = await checkedJson(fetchImpl, `${baseUrl}/models`, {
+    headers: { authorization: `Bearer ${secret}` },
+  }, "Tunnel model check");
+  if (!Array.isArray(models?.data)) {
+    throw new Error(`Tunnel model check returned an invalid catalog from ${baseUrl}/models`);
+  }
+
+  return { health, modelCount: models.data.length };
+}