clawdex-mobile 5.1.3-internal.6 → 5.1.3-internal.7

package/README.md

@@ -25,6 +25,7 @@ Before you start:
 - `git`
 - `codex` in `PATH` for the default Codex flow
 - `opencode` in `PATH` if you want the OpenCode flow
+- `cursor-app-server` in `PATH` if you want the Cursor SDK flow
 
 Install the mobile app:
 
@@ -70,8 +71,8 @@ Notes:
 - Browser preview uses a second forwarded port (`8788` by default), so both ports need public visibility.
 - GitHub resets public forwarded ports back to private when a codespace restarts. Restarting the bridge reruns the visibility step.
 - If automatic visibility setup fails, run `gh codespace ports visibility 8787:public 8788:public`.
-- If the mobile app is built with `EXPO_PUBLIC_GITHUB_APP_CLIENT_ID`, `EXPO_PUBLIC_GITHUB_APP_SLUG`, and `EXPO_PUBLIC_GITHUB_APP_AUTH_BASE_URL`, users can now tap `Use GitHub Codespaces` in onboarding/settings, complete one in-app GitHub App install/auth flow, pick a Codespace, and connect without manually copying the bridge token.
-- The tiny auth backend for that flow lives in `services/github-app-auth-worker`. Point the GitHub App callback URL at `https://<your-domain>/github/callback` and enable `Request user authorization (OAuth) during installation`.
+- If the mobile app is built with `EXPO_PUBLIC_GITHUB_APP_CLIENT_ID` and `EXPO_PUBLIC_GITHUB_APP_AUTH_BASE_URL`, users can now tap `Use GitHub Codespaces` in onboarding/settings, complete one in-app GitHub sign-in, pick a Codespace, and connect without manually copying the bridge token.
+- The tiny auth backend for that flow lives in `services/github-app-auth-worker`. Point the GitHub App callback URL at `https://<your-domain>/github/callback` and configure the worker with the GitHub App client ID/secret.
 - The app can also create a new repo-backed Codespace directly. It prefers `<signed-in-user>/<EXPO_PUBLIC_GITHUB_CODESPACES_REPO_NAME>` first. If that repo does not exist, it automatically forks `EXPO_PUBLIC_GITHUB_CODESPACES_SOURCE_OWNER/<EXPO_PUBLIC_GITHUB_CODESPACES_REPO_NAME>` into the signed-in user account, then creates the Codespace there.
 
 This repo now also includes a Codespaces bootstrap flow. On Codespace start/resume, `.devcontainer/devcontainer.json` runs:
@@ -86,29 +87,38 @@ During initial Codespace creation, the devcontainer also runs:
 npm run codespaces:bootstrap -- --prepare-only
 ```
 
-That pre-installs Codex and prebuilds the Rust bridge binary so the later startup path is faster. The normal bootstrap command rewrites `.env.secure` for Codespaces with `codex` as the only enabled engine and starts the bridge in the background. You can rerun either command manually any time.
+That pre-installs the selected engines and prebuilds the Rust bridge binary so the later startup path is faster. The normal bootstrap command rewrites `.env.secure` for Codespaces with `codex` as the default enabled engine and starts the bridge in the background. You can rerun either command manually any time.
+
+To enable more engines in Codespaces, set `CLAWDEX_CODESPACES_ENGINES` before bootstrap:
+
+```bash
+CLAWDEX_CODESPACES_ENGINES=codex,opencode,cursor npm run codespaces:bootstrap
+```
+
+When `opencode` or `cursor` are selected, bootstrap installs their CLI/server package if the command is missing. Cursor still needs `CURSOR_API_KEY` in the environment or `.env.secure`.
 
 The published npm package now includes that bootstrap script too, so a minimal Codespaces template repo can install `clawdex-mobile@latest` in `postCreateCommand` and call the packaged bootstrap without vendoring bridge source into the template itself.
 
 In Codespaces mode, the bootstrap also enables bridge-side GitHub bearer auth for the current `CODESPACE_NAME`, so the mobile app can authenticate with the same GitHub App user token it used to discover and start the Codespace.
 
-## OpenCode Setup
+## Extra Harness Setup
 
-OpenCode is supported directly from the CLI now.
+OpenCode and Cursor can run beside Codex from the same bridge.
 
 ```bash
 npm install -g opencode-ai
+npm install -g @clawdex/cursor-app-server
 npm install -g clawdex-mobile@latest
-clawdex init --engines codex,opencode
+clawdex init --engines codex,opencode,cursor
 ```
 
-That writes `BRIDGE_ENABLED_ENGINES=codex,opencode` to `.env.secure`, so the mobile app can control both harnesses from one bridge.
+That writes `BRIDGE_ENABLED_ENGINES=codex,opencode,cursor` to `.env.secure`, so the mobile app can control the selected harnesses from one bridge. When Cursor is selected, `clawdex init` asks for the Cursor API key and saves it in `.env.secure`.
 
 Notes:
 
 - `clawdex init` without flags now lets you multi-select harnesses in the wizard with Space, then Enter to continue.
-- Use `clawdex init --engine codex` or `clawdex init --engine opencode` if you want a single-harness setup.
-- Use `clawdex init --engines codex,opencode` if you want both non-interactively.
+- Use `clawdex init --engine codex`, `clawdex init --engine opencode`, or `clawdex init --engine cursor` if you want a single-harness setup.
+- For non-interactive host automation, set `CURSOR_API_KEY` before running setup. `CURSOR_MODEL` is optional; the app model picker sends the model for normal chats.
 
 ## Monorepo Development
 
@@ -140,7 +150,7 @@ Use `npm run setup:wizard -- --no-start` if you only want to write config.
 
 ## Main Commands
 
-- `clawdex init [--engine codex|opencode] [--engines codex,opencode] [--no-start]`
+- `clawdex init [--engine codex|opencode|cursor] [--engines codex,opencode,cursor] [--no-start]`
 - `clawdex stop`
 - `clawdex upgrade` / `clawdex update`
 - `clawdex version`

package/docs/setup-and-operations.md

@@ -6,21 +6,23 @@ This guide is the detailed companion to the top-level `README.md`.
 
 The setup wizard now lets you choose which harnesses the phone should control.
 
-If you want both Codex and OpenCode:
+If you want Codex, OpenCode, and Cursor:
 
 ```bash
-clawdex init --engines codex,opencode
+clawdex init --engines codex,opencode,cursor
 ```
 
 From a source checkout, the equivalent command is:
 
 ```bash
-npm run setup:wizard -- --engines codex,opencode
+npm run setup:wizard -- --engines codex,opencode,cursor
 ```
 
-That writes `BRIDGE_ENABLED_ENGINES=codex,opencode` into `.env.secure`, so the bridge starts both backends and the mobile app can control both from one UI.
+That writes `BRIDGE_ENABLED_ENGINES=codex,opencode,cursor` into `.env.secure`, so the bridge starts the selected backends and the mobile app can control them from one UI. When Cursor is selected, `clawdex init` asks for the Cursor API key and saves it in `.env.secure`.
 
-If you want only one harness, use `--engine codex` or `--engine opencode`.
+If you want only one harness, use `--engine codex`, `--engine opencode`, or `--engine cursor`.
+
+Cursor usage limits are not exposed by Cursor's public API today. The app shows key status, key metadata, runtime state, and models from Cursor; plan or weekly usage details remain in Cursor.
 
 ## Onboarding Output Cues
 
@@ -63,8 +65,8 @@ Important constraints:
 - Browser preview uses the preview port (`8788` by default), so that forwarded port must also be public
 - GitHub resets public forwarded ports back to private whenever the codespace restarts
 - Keep bridge auth enabled and use Codespaces only for repos you trust, because public forwarded ports are internet-reachable
-- If the mobile app build sets `EXPO_PUBLIC_GITHUB_APP_CLIENT_ID`, `EXPO_PUBLIC_GITHUB_APP_SLUG`, and `EXPO_PUBLIC_GITHUB_APP_AUTH_BASE_URL`, onboarding/settings can now open one GitHub App install/auth flow, approve only the repositories they want, start the Codespace, and connect directly with the same GitHub App user token instead of copying `BRIDGE_AUTH_TOKEN`
-- That same in-app GitHub sign-in also bootstraps GitHub git auth inside the Codespace so `git clone`, `git push`, GitHub HTTPS remotes, and common `git@github.com:...` SSH-style remotes can reuse the app login without extra account setup
+- If the mobile app build sets `EXPO_PUBLIC_GITHUB_APP_CLIENT_ID` and `EXPO_PUBLIC_GITHUB_APP_AUTH_BASE_URL`, onboarding/settings can now open one GitHub sign-in, start the Codespace, and connect directly with the same GitHub App user token instead of copying `BRIDGE_AUTH_TOKEN`
+- Users do not need to grant the GitHub App repository installation access to the `clawdex-codespace` template for the normal Codespaces flow
 - The same in-app GitHub flow can create a new Codespace. It prefers `<signed-in-user>/<EXPO_PUBLIC_GITHUB_CODESPACES_REPO_NAME>`. If that repo does not exist yet, Clawdex automatically forks `EXPO_PUBLIC_GITHUB_CODESPACES_SOURCE_OWNER/<EXPO_PUBLIC_GITHUB_CODESPACES_REPO_NAME>` into the signed-in user account and creates the Codespace from that fork
 - Older saved GitHub Codespaces sessions may need one fresh sign-in from the app so the stored GitHub App token and refresh token are updated
 
@@ -72,7 +74,6 @@ For the one-flow GitHub App setup:
 
 - deploy the tiny auth service under `services/github-app-auth-worker`
 - set the GitHub App `Callback URL` to `https://<your-domain>/github/callback`
-- enable `Request user authorization (OAuth) during installation`
 - set the mobile env `EXPO_PUBLIC_GITHUB_APP_AUTH_BASE_URL=https://<your-domain>`
 
 Manual recovery if port visibility does not update automatically:
@@ -92,9 +93,12 @@ The repo devcontainer now includes:
 
 - installs the Codex CLI via `npm install -g @openai/codex` if it is missing
 - in `--prepare-only` mode, prebuilds the Rust bridge binary without starting it
-- rewrites `.env.secure` for `BRIDGE_NETWORK_MODE=codespaces` with `BRIDGE_ACTIVE_ENGINE=codex`, `BRIDGE_ENABLED_ENGINES=codex`, and `BRIDGE_GITHUB_CODESPACES_AUTH=true`
+- rewrites `.env.secure` for `BRIDGE_NETWORK_MODE=codespaces`, `BRIDGE_GITHUB_CODESPACES_AUTH=true`, and the selected engine list
+- writes `CODEX_HOME=$HOME/.codex` in Codespaces so Codex-managed ChatGPT auth survives bridge restarts and Codespace wakes
 - starts the bridge in the background unless you set `CLAWDEX_CODESPACES_SKIP_START=true` or pass `--no-start`
 
+Clawdex-created Codespaces request a 45-minute idle timeout. The bridge emits a lightweight active-turn keepalive while a Codex, OpenCode, or Cursor turn is running, so active work has activity even if a long step is otherwise quiet. When no turn is running, the keepalive stops and GitHub can pause the Codespace normally to save cost.
+
 That means the first Codespace create now front-loads the expensive bridge compile during `postCreateCommand`, so the later `postStartCommand` can usually start the bridge much faster.
 
 The same bootstrap script is included in the published `clawdex-mobile` npm package. That lets the `clawdex-codespace` template stay minimal: it can install `clawdex-mobile@latest` globally in the devcontainer and invoke the packaged bootstrap against the current workspace instead of copying `scripts/*` and `services/rust-bridge/*` into the template repo.
@@ -105,6 +109,7 @@ Manual examples:
 npm run codespaces:bootstrap -- --prepare-only
 npm run codespaces:bootstrap
 npm run codespaces:bootstrap -- --no-start
+CLAWDEX_CODESPACES_ENGINES=codex,opencode,cursor npm run codespaces:bootstrap
 ```
 
 Minimal template equivalent:
@@ -129,10 +134,10 @@ npm install
 npm run secure:setup
 ```
 
-To generate OpenCode-first config instead:
+To generate multi-harness config instead:
 
 ```bash
-BRIDGE_ENABLED_ENGINES=codex,opencode npm run secure:setup
+BRIDGE_ENABLED_ENGINES=codex,opencode,cursor npm run secure:setup
 ```
 
 Creates/updates:
@@ -146,13 +151,13 @@ Creates/updates:
 npm run secure:bridge
 ```
 
-If you want a one-off OpenCode launch without rewriting `.env.secure`:
+If you want a one-off multi-harness launch without rewriting `.env.secure`:
 
 ```bash
-BRIDGE_ENABLED_ENGINES=codex,opencode npm run secure:bridge
+BRIDGE_ENABLED_ENGINES=codex,opencode,cursor npm run secure:bridge
 ```
 
-When both CLIs are selected, the bridge starts both backends and merges chat lists while still routing each thread by engine.
+When multiple harnesses are selected, the bridge starts each backend and merges chat lists while still routing each thread by engine.
 
 ### 4) Pair from the mobile app
 
@@ -274,10 +279,14 @@ npm run teardown -- --yes
 | `BRIDGE_GITHUB_CODESPACES_AUTH` | accept GitHub bearer tokens for the current codespace |
 | `BRIDGE_GITHUB_CODESPACE_NAME` | codespace name used when validating GitHub bearer tokens |
 | `BRIDGE_GITHUB_API_URL` | GitHub REST API base URL for Codespaces auth checks |
+| `CODEX_HOME` | Codex auth/config home; set to `$HOME/.codex` in Codespaces so ChatGPT auth persists across bridge restarts |
 | `CODEX_CLI_BIN` | codex executable |
 | `BRIDGE_ACTIVE_ENGINE` | internal preferred routing backend used when multiple harnesses are enabled |
-| `BRIDGE_ENABLED_ENGINES` | selected harnesses to expose (`codex`, `opencode`, or both) |
+| `BRIDGE_ENABLED_ENGINES` | selected harnesses to expose (`codex`, `opencode`, `cursor`, or a comma-separated mix) |
 | `OPENCODE_CLI_BIN` | opencode executable for dual-engine startup |
+| `CURSOR_APP_SERVER_BIN` | Cursor app-server executable, usually `cursor-app-server` |
+| `CURSOR_API_KEY` | Cursor API key used by the Cursor SDK harness; collected by `clawdex init` when Cursor is selected |
+| `CURSOR_MODEL` | optional Cursor model id for non-interactive host defaults; normal mobile chats send the selected model |
 | `BRIDGE_OPENCODE_HOST` | loopback host for spawned opencode server |
 | `BRIDGE_OPENCODE_PORT` | loopback port for spawned opencode server |
 | `BRIDGE_OPENCODE_SERVER_USERNAME` | basic-auth username passed to opencode server |
@@ -291,7 +300,7 @@ npm run teardown -- --yes
 |---|---|
 | `EXPO_PUBLIC_HOST_BRIDGE_TOKEN` | token used by local mobile dev builds |
 | `EXPO_PUBLIC_GITHUB_APP_CLIENT_ID` | GitHub App client ID for in-app Codespaces sign-in |
-| `EXPO_PUBLIC_GITHUB_APP_SLUG` | GitHub App slug used to open install/manage-access pages for repository selection |
+| `EXPO_PUBLIC_GITHUB_APP_SLUG` | optional GitHub App slug, reserved for future manage-access flows |
 | `EXPO_PUBLIC_GITHUB_APP_AUTH_BASE_URL` | HTTPS origin for the GitHub App auth worker (`/api/github/exchange`, `/api/github/refresh`, `/github/callback`) |
 | `EXPO_PUBLIC_GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN` | forwarded port domain used to derive Codespaces bridge URLs (`app.github.dev` by default) |
 | `EXPO_PUBLIC_GITHUB_CODESPACES_REPO_NAME` | repository name to sort matching Codespaces first in the in-app picker |

package/docs/troubleshooting.md

@@ -100,20 +100,27 @@ npm run codespaces:bootstrap -- --no-start
 
 ## Voice transcription says no credentials were found
 
-- The bridge can transcribe with either `OPENAI_API_KEY`, `BRIDGE_CHATGPT_ACCESS_TOKEN`, or the same ChatGPT auth tokens already used for Codex login.
-- In GitHub Codespaces, finish the ChatGPT/Codex login step from the app first. The bridge will persist those tokens to `BRIDGE_WORKDIR/.clawdex-chatgpt-auth.json` and reuse them for voice transcription.
-- If you still see the error after logging in, restart the bridge once so it reloads the persisted auth cache:
+- The bridge can transcribe with `OPENAI_API_KEY`, `BRIDGE_CHATGPT_ACCESS_TOKEN`, a legacy bridge token cache, or the Codex-managed ChatGPT token in `$CODEX_HOME/auth.json`.
+- In GitHub Codespaces, finish the Codex login step from the app first. Codex writes the login to `$HOME/.codex/auth.json`, and `.env.secure` sets `CODEX_HOME` to that persistent location.
+- If you still see the error after logging in, restart the bridge once so app-server reloads the Codex auth home:
 
 ```bash
 npm run secure:bridge
 ```
 
-- You can inspect whether the bridge captured the token bundle:
+- You can inspect whether Codex saved auth in the Codespace:
 
 ```bash
-ls -la .clawdex-chatgpt-auth.json
+ls -la "${CODEX_HOME:-$HOME/.codex}/auth.json"
 ```
 
+## Codespace wakes but Codex says account authentication is required
+
+- Codespaces should use Codex-managed auth, the same as a local bridge. The login is stored in `${CODEX_HOME:-$HOME/.codex}/auth.json`.
+- The app starts Codex's normal ChatGPT web login first. It captures the OAuth callback on the phone and forwards that callback to the Codex loopback server inside the Codespace, so device-code login is only a fallback.
+- Run `source .env.secure && ls -la "$CODEX_HOME/auth.json"` in the Codespace to confirm the auth file exists.
+- If the file is missing, reopen GitHub Codespaces setup in the app and complete the Codex login step once. After that, bridge restarts and Codespace wakes should not require reauthentication.
+
 ## Local browser preview does not open
 
 - The in-app browser only supports loopback targets from the bridge host: `localhost`, `127.0.0.1`, or `::1`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawdex-mobile",
-  "version": "5.1.3-internal.6",
+  "version": "5.1.3-internal.7",
   "description": "Private-network mobile bridge and CLI for Codex and OpenCode",
   "keywords": [
     "codex",
@@ -67,7 +67,7 @@
     "build": "npm run --workspaces build",
     "typecheck": "npm run --workspaces typecheck",
     "lint": "npm run --workspaces lint",
-    "test": "npm run test -w @codex/mac-bridge && npm run test -w apps/mobile && npm run test -w @codex/rust-bridge",
+    "test": "npm run test -w @codex/mac-bridge && npm run test -w apps/mobile && npm run test -w @codex/rust-bridge && npm run test -w @clawdex/cursor-app-server",
     "teardown": "./scripts/teardown.sh"
   }
 }

package/scripts/codespaces-bootstrap.js

@@ -90,6 +90,25 @@ function parseArgs(argv) {
   };
 }
 
+function parseEngineList(value) {
+  const raw = typeof value === "string" && value.trim() ? value : "codex";
+  const engines = [];
+  for (const entry of raw.split(",")) {
+    const engine = entry.trim().toLowerCase();
+    if (!engine) {
+      continue;
+    }
+    if (!["codex", "opencode", "cursor"].includes(engine)) {
+      console.error(`error: unsupported Codespaces engine '${engine}'. Use codex, opencode, or cursor.`);
+      process.exit(1);
+    }
+    if (!engines.includes(engine)) {
+      engines.push(engine);
+    }
+  }
+  return engines.length > 0 ? engines : ["codex"];
+}
+
 function ensureCodespacesContext({ force }) {
   if (force) {
     return;
@@ -104,6 +123,9 @@ function ensureCodespacesContext({ force }) {
 }
 
 function runSetup(rootDir, workspaceDir) {
+  const enabledEngines = parseEngineList(
+    process.env.CLAWDEX_CODESPACES_ENGINES || process.env.BRIDGE_ENABLED_ENGINES || "codex"
+  );
   const setupEnv = {
     ...process.env,
   };
@@ -117,10 +139,10 @@ function runSetup(rootDir, workspaceDir) {
   setupEnv.CLAWDEX_WORKSPACE_ROOT = workspaceDir;
   setupEnv.BRIDGE_NETWORK_MODE = "codespaces";
   setupEnv.BRIDGE_HOST_OVERRIDE = "127.0.0.1";
-  setupEnv.BRIDGE_ACTIVE_ENGINE = "codex";
-  setupEnv.BRIDGE_ENABLED_ENGINES = "codex";
+  setupEnv.BRIDGE_ACTIVE_ENGINE = enabledEngines[0];
+  setupEnv.BRIDGE_ENABLED_ENGINES = enabledEngines.join(",");
 
-  console.log("Preparing .env.secure for GitHub Codespaces...");
+  console.log(`Preparing .env.secure for GitHub Codespaces (${setupEnv.BRIDGE_ENABLED_ENGINES})...`);
   const result = runCommand(path.join(rootDir, "scripts", "setup-secure-dev.sh"), [], {
     cwd: workspaceDir,
     env: setupEnv,
@@ -156,6 +178,50 @@ function ensureCodexCliInstalled(secureEnv) {
   console.log("Codex CLI installed.");
 }
 
+function ensureNpmGlobalBinary({ binary, packageName, label }) {
+  if (commandExists(binary)) {
+    return;
+  }
+
+  console.log(`${label} not found in this codespace. Installing via npm...`);
+  const installResult = runCommand("npm", ["install", "-g", packageName], {
+    cwd: resolveWorkspaceDir(),
+    env: process.env,
+  });
+  if ((installResult.status ?? 1) !== 0) {
+    console.error(`error: failed to install ${label} automatically.`);
+    process.exit(installResult.status ?? 1);
+  }
+
+  if (!commandExists(binary)) {
+    console.error(`error: ${label} still not found after install attempt: ${binary}`);
+    process.exit(1);
+  }
+
+  console.log(`${label} installed.`);
+}
+
+function ensureSelectedEngineTools(secureEnv) {
+  const enabledEngines = parseEngineList(readNonEmptyEnv(secureEnv, "BRIDGE_ENABLED_ENGINES") || "codex");
+  if (enabledEngines.includes("codex")) {
+    ensureCodexCliInstalled(secureEnv);
+  }
+  if (enabledEngines.includes("opencode")) {
+    ensureNpmGlobalBinary({
+      binary: readNonEmptyEnv(secureEnv, "OPENCODE_CLI_BIN") || "opencode",
+      packageName: "opencode-ai",
+      label: "OpenCode CLI",
+    });
+  }
+  if (enabledEngines.includes("cursor")) {
+    ensureNpmGlobalBinary({
+      binary: readNonEmptyEnv(secureEnv, "CURSOR_APP_SERVER_BIN") || "cursor-app-server",
+      packageName: "@clawdex/cursor-app-server",
+      label: "Cursor app server",
+    });
+  }
+}
+
 function prepareBridgeBinary(rootDir, workspaceDir, secureEnv) {
   console.log("Prebuilding bridge binary for faster Codespaces startup...");
   const prepareEnv = {
@@ -219,7 +285,7 @@ function main() {
     return;
   }
 
-  ensureCodexCliInstalled(secureEnv);
+  ensureSelectedEngineTools(secureEnv);
   if (options.prepareOnly) {
     prepareBridgeBinary(rootDir, workspaceDir, secureEnv);
     console.log("Codespaces bootstrap prepared Codex and the bridge binary without starting the bridge.");

package/scripts/setup-secure-dev.sh

@@ -13,6 +13,9 @@ MOBILE_ENV_EXAMPLE="$ROOT_DIR/apps/mobile/.env.example"
 BRIDGE_ACTIVE_ENGINE="${BRIDGE_ACTIVE_ENGINE:-codex}"
 BRIDGE_ENABLED_ENGINES="${BRIDGE_ENABLED_ENGINES:-$BRIDGE_ACTIVE_ENGINE}"
 OPENCODE_CLI_BIN="${OPENCODE_CLI_BIN:-opencode}"
+CURSOR_APP_SERVER_BIN="${CURSOR_APP_SERVER_BIN:-cursor-app-server}"
+CURSOR_API_KEY="${CURSOR_API_KEY:-}"
+CURSOR_MODEL="${CURSOR_MODEL:-}"
 BRIDGE_CONNECT_URL=""
 BRIDGE_PREVIEW_CONNECT_URL=""
 
@@ -278,10 +281,10 @@ case "$BRIDGE_NETWORK_MODE" in
 esac
 
 case "$BRIDGE_ACTIVE_ENGINE" in
-  codex|opencode)
+  codex|opencode|cursor)
     ;;
   *)
-    echo "error: BRIDGE_ACTIVE_ENGINE must be 'codex' or 'opencode'." >&2
+    echo "error: BRIDGE_ACTIVE_ENGINE must be 'codex', 'opencode', or 'cursor'." >&2
     exit 1
     ;;
 esac
@@ -301,7 +304,7 @@ validate_enabled_engines() {
       continue
     fi
     case "$normalized" in
-      codex|opencode)
+      codex|opencode|cursor)
         ;;
       *)
         return 1
@@ -323,7 +326,7 @@ validate_enabled_engines() {
 }
 
 if ! validate_enabled_engines "$BRIDGE_ENABLED_ENGINES"; then
-  echo "error: BRIDGE_ENABLED_ENGINES must contain one or more of 'codex' and 'opencode'." >&2
+  echo "error: BRIDGE_ENABLED_ENGINES must contain one or more of 'codex', 'opencode', and 'cursor'." >&2
   exit 1
 fi
 
@@ -382,9 +385,13 @@ fi
 
 GITHUB_CODESPACES_AUTH_ENABLED="false"
 GITHUB_CODESPACES_NAME=""
+CODEX_HOME_ENV_BLOCK=""
 if [[ "$BRIDGE_NETWORK_MODE" == "codespaces" ]]; then
   GITHUB_CODESPACES_AUTH_ENABLED="true"
   GITHUB_CODESPACES_NAME="$(printf '%s' "${CODESPACE_NAME:-}" | tr -d '[:space:]')"
+  CODEX_AUTH_HOME="${CODEX_HOME:-$HOME/.codex}"
+  mkdir -p "$CODEX_AUTH_HOME"
+  CODEX_HOME_ENV_BLOCK="CODEX_HOME=$CODEX_AUTH_HOME"
 fi
 
 cat > "$SECURE_ENV_FILE" <<EOT
@@ -401,8 +408,12 @@ BRIDGE_GITHUB_CODESPACE_NAME=$GITHUB_CODESPACES_NAME
 BRIDGE_GITHUB_API_URL=https://api.github.com
 BRIDGE_ACTIVE_ENGINE=$BRIDGE_ACTIVE_ENGINE
 BRIDGE_ENABLED_ENGINES=$BRIDGE_ENABLED_ENGINES
+$CODEX_HOME_ENV_BLOCK
 CODEX_CLI_BIN=codex
 OPENCODE_CLI_BIN=$OPENCODE_CLI_BIN
+CURSOR_APP_SERVER_BIN=$CURSOR_APP_SERVER_BIN
+CURSOR_API_KEY=$CURSOR_API_KEY
+CURSOR_MODEL=$CURSOR_MODEL
 BRIDGE_WORKDIR=$ROOT_DIR
 EOT
 

package/scripts/setup-wizard.sh

@@ -37,6 +37,7 @@ declare -a SELECTED_ENGINES=()
 ENGINE_SELECTION_PRESET="false"
 AUTO_START="true"
 SECURE_ENV_FILE="$ROOT_DIR/.env.secure"
+CURSOR_CONFIG_NEEDS_WRITE="false"
 MENU_RESULT=""
 MENU_MULTI_RESULT=""
 MENU_MULTI_PRESELECTED=""
@@ -86,9 +87,9 @@ Usage: $(basename "$0") [options]
 
 Options:
   --no-start               Configure everything but do not start bridge
-  --engine <codex|opencode>
+  --engine <codex|opencode|cursor>
                            Select a single harness non-interactively
-  --engines <codex,opencode>
+  --engines <codex,opencode,cursor>
                            Select one or more harnesses non-interactively
   -h, --help               Show this help
 EOF
@@ -96,7 +97,7 @@ EOF
 
 validate_engine_name() {
   case "$1" in
-    codex|opencode)
+    codex|opencode|cursor)
       return 0
       ;;
     *)
@@ -110,6 +111,9 @@ format_engine_name() {
     opencode)
       printf 'OpenCode'
       ;;
+    cursor)
+      printf 'Cursor'
+      ;;
     *)
       printf 'Codex'
       ;;
@@ -251,6 +255,9 @@ engine_from_menu_label() {
     "OpenCode")
       printf 'opencode'
       ;;
+    "Cursor")
+      printf 'cursor'
+      ;;
     *)
       return 1
       ;;
@@ -295,12 +302,12 @@ parse_args() {
         ;;
       --engine)
         if (($# < 2)); then
-          echo "error: --engine requires a value ('codex' or 'opencode')." >&2
+          echo "error: --engine requires a value ('codex', 'opencode', or 'cursor')." >&2
           print_usage >&2
           exit 1
         fi
         if ! validate_engine_name "$2"; then
-          echo "error: unsupported engine '$2'. Use 'codex' or 'opencode'." >&2
+          echo "error: unsupported engine '$2'. Use 'codex', 'opencode', or 'cursor'." >&2
           print_usage >&2
           exit 1
         fi
@@ -311,12 +318,12 @@ parse_args() {
         ;;
       --engines)
         if (($# < 2)); then
-          echo "error: --engines requires a comma-separated value (for example: codex,opencode)." >&2
+          echo "error: --engines requires a comma-separated value (for example: codex,opencode,cursor)." >&2
           print_usage >&2
           exit 1
         fi
         if ! parse_engine_list_csv "$2"; then
-          echo "error: unsupported --engines value '$2'. Use one or more of 'codex' and 'opencode'." >&2
+          echo "error: unsupported --engines value '$2'. Use one or more of 'codex', 'opencode', and 'cursor'." >&2
           print_usage >&2
           exit 1
         fi
@@ -916,6 +923,25 @@ prompt_manual_ipv4() {
   done
 }
 
+prompt_secret_value() {
+  local prompt="$1"
+  local value=""
+
+  while true; do
+    printf "%s %s %s " "$RAIL_GLYPH" "$RAIL_BRANCH" "$prompt" >&2
+    IFS= read -rs value || abort_wizard
+    printf "\n" >&2
+    value="$(printf '%s' "$value" | tr -d '\r\n')"
+
+    if [[ -n "$value" ]]; then
+      printf '%s' "$value"
+      return 0
+    fi
+
+    printf "%s %s %s\n" "$RAIL_GLYPH" "$RAIL_CHILD" "${YELLOW}Value cannot be empty.${RESET}" >&2
+  done
+}
+
 extract_env_value() {
   local file="$1"
   local key="$2"
@@ -1141,9 +1167,15 @@ choose_runtime_engine() {
     fi
     MENU_MULTI_PRESELECTED+="OpenCode"
   fi
+  if selected_engines_contains "cursor"; then
+    if [[ -n "$MENU_MULTI_PRESELECTED" ]]; then
+      MENU_MULTI_PRESELECTED+=","
+    fi
+    MENU_MULTI_PRESELECTED+="Cursor"
+  fi
 
   info "Select the harnesses this phone should control."
-  menu_multiselect "Harnesses to control" "Codex" "OpenCode"
+  menu_multiselect "Harnesses to control" "Codex" "OpenCode" "Cursor"
   SELECTED_ENGINES=()
   for label in "${MENU_MULTI_RESULT_ITEMS[@]}"; do
     SELECTED_ENGINES+=("$(engine_from_menu_label "$label")")
@@ -1274,6 +1306,66 @@ ensure_opencode_cli() {
   fi
 }
 
+ensure_cursor_app_server() {
+  local existing_api_key=""
+  local existing_model=""
+  local provided_api_key="${CURSOR_API_KEY:-}"
+
+  if [[ -f "$ROOT_DIR/services/cursor-app-server/package.json" ]]; then
+    info "Building Cursor app-server package."
+    npm run build -w @clawdex/cursor-app-server
+    hash -r
+  fi
+
+  while ! command -v cursor-app-server >/dev/null 2>&1; do
+    warn "Cursor app-server command not found in PATH."
+    if confirm_prompt "Try installing @clawdex/cursor-app-server via npm now?" "N"; then
+      if npm install -g @clawdex/cursor-app-server; then
+        hash -r
+      else
+        warn "Automatic install failed."
+      fi
+    fi
+
+    if ! command -v cursor-app-server >/dev/null 2>&1 && ! confirm_prompt "Retry Cursor app-server check?" "Y"; then
+      abort_wizard "Install @clawdex/cursor-app-server and rerun: clawdex init --engine cursor"
+    fi
+  done
+
+  ok "Found cursor-app-server: $(command -v cursor-app-server)"
+
+  existing_api_key="$(extract_env_value "$SECURE_ENV_FILE" "CURSOR_API_KEY")"
+  existing_model="$(extract_env_value "$SECURE_ENV_FILE" "CURSOR_MODEL")"
+  CURSOR_API_KEY="${CURSOR_API_KEY:-$existing_api_key}"
+  CURSOR_MODEL="${CURSOR_MODEL:-$existing_model}"
+
+  if [[ -n "$CURSOR_API_KEY" ]]; then
+    if [[ -n "$provided_api_key" ]]; then
+      ok "Cursor API key: provided from environment."
+      if [[ "$provided_api_key" != "$existing_api_key" ]]; then
+        CURSOR_CONFIG_NEEDS_WRITE="true"
+      fi
+    else
+      ok "Cursor API key: configured in secure bridge config."
+    fi
+    if [[ "$FLOW" == "manual" ]] && confirm_prompt "Replace saved Cursor API key now?" "N"; then
+      CURSOR_API_KEY="$(prompt_secret_value "Enter Cursor API key:")"
+      CURSOR_CONFIG_NEEDS_WRITE="true"
+      ok "Cursor API key will be updated in $SECURE_ENV_FILE."
+    fi
+  else
+    warn "Cursor requires a Cursor API key on the bridge host."
+    if ! confirm_prompt "Add Cursor API key now?" "Y"; then
+      abort_wizard "Cursor was selected but CURSOR_API_KEY is missing. Re-run clawdex init after creating a Cursor API key."
+    fi
+    CURSOR_API_KEY="$(prompt_secret_value "Enter Cursor API key:")"
+    CURSOR_CONFIG_NEEDS_WRITE="true"
+    ok "Cursor API key will be saved in $SECURE_ENV_FILE."
+  fi
+
+  export CURSOR_API_KEY CURSOR_MODEL
+}
+
 ensure_selected_engine_clis() {
   local engine=""
 
@@ -1289,6 +1381,9 @@ ensure_selected_engine_clis() {
       opencode)
         ensure_opencode_cli
         ;;
+      cursor)
+        ensure_cursor_app_server
+        ;;
       *)
         abort_wizard "Unsupported harness '$engine'."
         ;;
@@ -1795,6 +1890,9 @@ else
   elif [[ "$(extract_env_value "$SECURE_ENV_FILE" "BRIDGE_ENABLED_ENGINES")" != "$(selected_engines_csv)" ]]; then
     section "Write secure config"
     BRIDGE_NETWORK_MODE="$NETWORK_MODE" BRIDGE_HOST_OVERRIDE="$BRIDGE_HOST" BRIDGE_ACTIVE_ENGINE="$ACTIVE_ENGINE" BRIDGE_ENABLED_ENGINES="$(selected_engines_csv)" "$SCRIPT_DIR/setup-secure-dev.sh"
+  elif [[ "$CURSOR_CONFIG_NEEDS_WRITE" == "true" ]]; then
+    section "Write secure config"
+    BRIDGE_NETWORK_MODE="$NETWORK_MODE" BRIDGE_HOST_OVERRIDE="$BRIDGE_HOST" BRIDGE_ACTIVE_ENGINE="$ACTIVE_ENGINE" BRIDGE_ENABLED_ENGINES="$(selected_engines_csv)" "$SCRIPT_DIR/setup-secure-dev.sh"
   fi
 fi
 

package/scripts/start-bridge-secure.js

@@ -848,8 +848,8 @@ async function start() {
 
   const fileEnv = readEnvFile(secureEnvFile);
   const env = {
-    ...fileEnv,
     ...process.env,
+    ...fileEnv,
     CLAWDEX_WORKSPACE_ROOT: workspaceDir,
     INIT_CWD: process.env.INIT_CWD || workspaceDir,
   };

package/services/rust-bridge/Cargo.lock

@@ -149,7 +149,7 @@ dependencies = [
 
 [[package]]
 name = "codex-rust-bridge"
-version = "5.1.3-internal.6"
+version = "5.1.3-internal.7"
 dependencies = [
  "axum",
  "base64",

package/services/rust-bridge/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "codex-rust-bridge"
-version = "5.1.3-internal.6"
+version = "5.1.3-internal.7"
 edition = "2021"
 
 [dependencies]