pennyrouter 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pennyrouter",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Install and manage PennyRouter local coding-agent integrations.",
   "homepage": "https://pennyrouter.com",
   "bugs": {

package/src/cli.js

@@ -1,5 +1,6 @@
 import { spawn, spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { hostname } from "node:os";
 import { emitKeypressEvents } from "node:readline";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
@@ -30,6 +31,7 @@ import {
   maskKey,
   pollForKey,
   probeClaudeCodeGateway,
+  provisionPrivateGatewayKey,
   sleep,
   storeAnthropicToken,
   storeUpstreamCredential,
@@ -193,15 +195,40 @@ function parseArgs(argv) {
     else if (arg.startsWith("--openrouter-api-key=")) flags.openrouterApiKey = arg.slice("--openrouter-api-key=".length);
     else if (arg === "--harness") flags.harness = rest[++i] || "";
     else if (arg.startsWith("--harness=")) flags.harness = arg.slice("--harness=".length);
+    // --private-gateway [url]: install against a self-hosted gateway. Unlike
+    // --gateway-base-url, which expects the URL and an admin-issued key up front, this asks
+    // for what it needs (gateway URL, then email) and mints the key from the gateway itself,
+    // so a user on a VPN can install without an administrator handing them a key first.
+    else if (arg === "--private-gateway") {
+      flags.privateGatewayFlow = true;
+      flags.privateGateway = true;
+      // Optional inline URL: `--private-gateway https://...` rather than a prompt. Only
+      // consume the next argument when it is not itself a flag.
+      if (rest[i + 1] && !rest[i + 1].startsWith("-")) flags.gatewayBaseUrl = rest[++i];
+    }
+    else if (arg.startsWith("--private-gateway=")) {
+      flags.privateGatewayFlow = true;
+      flags.privateGateway = true;
+      flags.gatewayBaseUrl = arg.slice("--private-gateway=".length);
+    }
+    // Email the private gateway mints the key against; prompted for when absent.
+    else if (arg === "--email") flags.email = rest[++i] || "";
+    else if (arg.startsWith("--email=")) flags.email = arg.slice("--email=".length);
     else if (arg === "--app-url") flags.appUrl = rest[++i] || "";
     else if (arg.startsWith("--app-url=")) flags.appUrl = arg.slice("--app-url=".length);
-    // A --gateway-base-url is a *private* gateway: an admin-run deployment that issues its own
-    // keys. Flag it so install can require the matching admin-issued key. --local/--prod are
-    // developer shortcuts against gateways that honor prod keys, so they do not set this.
-    else if (arg === "--gateway-base-url") { flags.gatewayBaseUrl = rest[++i] || ""; flags.privateGateway = true; }
+    // A --gateway-base-url is a *private* gateway: an admin-run deployment with its own key
+    // store, so it takes the same install path as --private-gateway (which supplies the URL
+    // interactively instead). --local/--prod are developer shortcuts against gateways that
+    // honor prod keys, so they do not set this.
+    else if (arg === "--gateway-base-url") {
+      flags.gatewayBaseUrl = rest[++i] || "";
+      flags.privateGateway = true;
+      flags.privateGatewayFlow = true;
+    }
     else if (arg.startsWith("--gateway-base-url=")) {
       flags.gatewayBaseUrl = arg.slice("--gateway-base-url=".length);
       flags.privateGateway = true;
+      flags.privateGatewayFlow = true;
     }
     // Admin-issued key for a private gateway (see scripts/provision_local_key.py). Overrides the
     // key returned by the browser claim, which is only valid against the hosted gateway.
@@ -265,13 +292,19 @@ export function applyConfigFile(flags) {
     }
   }
 
-  // A private gateway is independent of funding: it changes where the CLI claims its key and
+  // A private gateway is independent of funding: it changes where the CLI gets its key and
   // stores credentials, so it applies whatever providers were picked.
   for (const field of INSTALL_MANIFEST.advanced.fields) {
     const value = String(config[field.config_key] || "").trim();
     if (value && flags[field.config_key] === undefined) flags[field.config_key] = value;
   }
-  if (flags.gatewayBaseUrl) flags.privateGateway = true;
+  if (flags.gatewayBaseUrl) {
+    flags.privateGateway = true;
+    // Take the self-hosted install path rather than the hosted browser claim, whose key is
+    // meaningless against a gateway with its own account store. The key comes from
+    // --private-key when the config carried one, and is otherwise minted from the email.
+    flags.privateGatewayFlow = true;
+  }
 
   flags.yes = true;
   flags.fromConfig = true;
@@ -599,6 +632,29 @@ export async function install(flags = {}) {
       || globalAuth.gatewayBaseUrl
       || process.env.PENNYROUTER_GATEWAY_BASE_URL
       || DEFAULT_GATEWAY_BASE_URL;
+  } else if (flags.privateGatewayFlow) {
+    // A self-hosted gateway keeps its own accounts, so the hosted browser claim would mint a
+    // key against a store this install never talks to. Ask for the gateway, mint there, and
+    // skip the claim entirely.
+    gatewayBaseUrl = await resolvePrivateGatewayUrl(flags);
+    claim = { api_key: await obtainPrivateGatewayKey(flags, gatewayBaseUrl), gateway_base_url: gatewayBaseUrl };
+
+    const claudeProviders = await selectClaudeFundingProviders(flags, needsAuth);
+    const codexProviders = await selectCodexFundingProviders(flags, needsAuth);
+    claudeAnthropicAuth = await maybeConfigureClaudeAnthropicAuth(
+      flags, needsAuth, claudeProviders.has("subscription"));
+    funding = await configureUserFunding(
+      flags, needsAuth, claudeAnthropicAuth, claudeProviders, codexProviders);
+
+    for (const credential of funding.credentials) {
+      await withGatewayContext(gatewayBaseUrl, () => storeUpstreamCredential({
+        gatewayBaseUrl,
+        apiKey: claim.api_key,
+        provider: credential.provider,
+        token: credential.token,
+        metadata: credential.metadata,
+      }));
+    }
   } else {
     const session = await createCliSession({
       appUrl: flags.appUrl || APP_URL,
@@ -634,58 +690,6 @@ export async function install(flags = {}) {
       gatewayBaseUrl = normalized;
     }
 
-    // A user-supplied proxy may live on a private network that the hosted gateway cannot
-    // reach. Let interactive installs choose the gateway after they choose the proxy: blank
-    // keeps the hosted default, while a supplied URL is used for credential storage,
-    // validation, probing, and the installed harness configuration. `--local` remains the
-    // explicit localhost:8400 developer shortcut and skips this prompt.
-    if ((claudeProviders.has("anthropic-proxy") || codexProviders.has("openai-proxy")) && !flags.gatewayBaseUrl
-        && !flags.yes && input.isTTY && output.isTTY) {
-      const answer = (await promptText(
-        "PennyRouter gateway URL for this proxy (blank for hosted gateway): ",
-      )).trim();
-      if (answer) {
-        const privateGateway = normalizeGatewayBaseUrl(answer);
-        if (!privateGateway) {
-          throw new Error(
-            `"${answer}" is not a usable gateway URL. Use a host like `
-            + "localhost:8400 or https://gateway.example.com.",
-          );
-        }
-        // Show the normalized form: the user typed "localhost:8000" and everything from here on
-        // uses "http://localhost:8000", so any later error names a URL they recognize.
-        if (privateGateway !== answer) console.log(`Using gateway ${privateGateway}.`);
-        gatewayBaseUrl = privateGateway;
-        flags.privateGateway = true;
-      }
-    }
-
-    // A private gateway has its own key store, so the hosted key from the browser claim is
-    // meaningless there. Require the admin-issued key and use it for every subsequent gateway
-    // call (credential storage, probing, harness config).
-    if (flags.privateGateway) {
-      let privateKey = (flags.privateKey || "").trim();
-      if (!privateKey && !flags.yes && input.isTTY && output.isTTY) {
-        console.log("");
-        console.log(`Private gateway: ${gatewayBaseUrl}`);
-        console.log("Your PennyRouter administrator issues keys for this gateway.");
-        // No echo: this is an issued credential, and a visible paste lingers in scrollback.
-        privateKey = (await promptSecretish("Paste your private gateway key (pr-...): ")).trim();
-      }
-      if (!privateKey) {
-        throw new Error(
-          `A private gateway (${gatewayBaseUrl}) needs its own key. `
-          + "Ask your PennyRouter administrator for one and pass `--private-key pr-...`.",
-        );
-      }
-      if (!privateKey.startsWith("pr-")) {
-        throw new Error(`That does not look like a PennyRouter key — expected it to start with "pr-".`);
-      }
-      claim.api_key = privateKey;
-      console.log(`Using private gateway key ${maskKey(privateKey)}.`);
-      console.log("");
-    }
-
     for (const credential of funding.credentials) {
       await withGatewayContext(gatewayBaseUrl, () => storeUpstreamCredential({
         gatewayBaseUrl,
@@ -886,6 +890,74 @@ function mcpTargets(flags) {
    "fetch failed" long after the prompt, where the cause is invisible. Supply the obvious scheme
    (plain http for loopback, https elsewhere) and prove the result parses, so a typo fails here
    instead. Returns null when the value cannot be salvaged. */
+/* Resolve the private gateway's URL, prompting when it was not given inline. Normalizing
+   here means every later message (credential storage, probe, harness config) names the same
+   URL the user will recognize. */
+async function resolvePrivateGatewayUrl(flags) {
+  let raw = (flags.gatewayBaseUrl || "").trim();
+  if (!raw) {
+    if (flags.yes || !input.isTTY || !output.isTTY) {
+      throw new Error(
+        "--private-gateway needs the gateway URL in a non-interactive install: "
+        + "`--private-gateway https://gateway.example.com`.",
+      );
+    }
+    raw = await promptText("PennyRouter gateway URL: ");
+  }
+  const normalized = normalizeGatewayBaseUrl(raw);
+  if (!normalized) {
+    throw new Error(
+      `"${raw}" is not a usable gateway URL. Use a host like `
+      + "localhost:8400 or https://gateway.example.com.",
+    );
+  }
+  if (normalized !== raw.replace(/\/+$/, "")) console.log(`Using gateway ${normalized}.`);
+  return normalized;
+}
+
+/* The key for a private gateway: an admin-issued one if the user has it, otherwise minted
+   from the gateway itself against their email. --private-key wins so an administrator can
+   still hand out keys on a gateway that also allows self-service. */
+async function obtainPrivateGatewayKey(flags, gatewayBaseUrl) {
+  const issued = (flags.privateKey || "").trim();
+  if (issued) {
+    if (!issued.startsWith("pr-")) {
+      throw new Error(`That does not look like a PennyRouter key — expected it to start with "pr-".`);
+    }
+    console.log(`Using private gateway key ${maskKey(issued)}.`);
+    console.log("");
+    return issued;
+  }
+
+  let email = (flags.email || "").trim();
+  if (!email) {
+    if (flags.yes || !input.isTTY || !output.isTTY) {
+      throw new Error(
+        "--private-gateway needs an email in a non-interactive install: `--email you@example.com` "
+        + "(or pass an admin-issued `--private-key pr-...`).",
+      );
+    }
+    console.log("");
+    console.log(`Private gateway: ${gatewayBaseUrl}`);
+    email = await promptText("Your email (identifies your account on this gateway): ");
+  }
+  if (!email.includes("@")) throw new Error(`"${email}" is not a valid email address.`);
+
+  // Names the key after this machine so a user with several installs can tell their keys
+  // apart in the account's key list.
+  const machine = hostname().split(".")[0] || "default";
+  const result = await withGatewayContext(gatewayBaseUrl, () => provisionPrivateGatewayKey({
+    gatewayBaseUrl, email, name: machine,
+  }));
+  if (!result?.api_key) throw new Error("The gateway did not return a key.");
+  console.log(result.created_account
+    ? `Created your account on ${gatewayBaseUrl}.`
+    : `Added this machine to your existing account on ${gatewayBaseUrl}.`);
+  console.log(`Received key ${maskKey(result.api_key)}.`);
+  console.log("");
+  return result.api_key;
+}
+
 function normalizeGatewayBaseUrl(raw) {
   const value = String(raw || "").trim().replace(/\/+$/, "");
   if (!value) return null;
@@ -1231,7 +1303,9 @@ async function selectClaudeFundingProviders(flags, selected) {
   return promptFundingProviderCheckboxes(
     CLAUDE_PROVIDER_OPTIONS,
     "Which providers should PennyRouter use for Claude Code?",
-    new Set(["subscription"]),
+    // An enterprise gateway usually fronts the model provider itself, so the proxy is the
+    // expected answer there and leads; elsewhere the subscription does.
+    new Set([flags.privateGatewayFlow ? "anthropic-proxy" : "subscription"]),
   );
 }
 
@@ -1254,7 +1328,7 @@ async function selectCodexFundingProviders(flags, selected) {
   return promptFundingProviderCheckboxes(
     CODEX_PROVIDER_OPTIONS,
     "Which providers should PennyRouter use for Codex?",
-    new Set(["subscription"]),
+    new Set([flags.privateGatewayFlow ? "openai-proxy" : "subscription"]),
   );
 }
 
@@ -2180,7 +2254,7 @@ function printHelp() {
   console.log(`PennyRouter CLI
 
 Usage:
-  pennyrouter install [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--dry-run] [--make-default|--penny-only] [--no-path-update] [--no-mcp] [--anthropic-auth|--no-anthropic-auth] [--anthropic-api-key KEY] [--openai-api-key KEY] [--openai-proxy-base-url URL --openai-proxy-api-key KEY] [--openrouter-api-key KEY] [--proxy-base-url URL --proxy-api-key KEY] [--gateway-base-url URL --private-key pr-...] [--local[=URL]|--prod] [--config PATH]
+  pennyrouter install [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--dry-run] [--make-default|--penny-only] [--no-path-update] [--no-mcp] [--anthropic-auth|--no-anthropic-auth] [--anthropic-api-key KEY] [--openai-api-key KEY] [--openai-proxy-base-url URL --openai-proxy-api-key KEY] [--openrouter-api-key KEY] [--proxy-base-url URL --proxy-api-key KEY] [--private-gateway[=URL] [--email you@example.com]] [--gateway-base-url URL] [--private-key pr-...] [--local[=URL]|--prod] [--config PATH]
   pennyrouter update [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--dry-run] [--penny-key pr-...] [--gateway-base-url URL|--local[=URL]|--prod] [--no-mcp]
   pennyrouter auth anthropic [--penny-key pr-...] [--token oauth-token] [--token-command CMD] [--gateway-base-url URL] [--forget]
   pennyrouter disable [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes]
@@ -2189,13 +2263,14 @@ Usage:
   pennyrouter status
   pennyrouter mcp install|uninstall|status [--harness claude-code,codex]
 
-When an interactive install selects an Anthropic or OpenAI-compatible proxy, it asks for the PennyRouter gateway
-that can reach that proxy. Leave it blank for the hosted gateway, or enter a private/self-hosted
-gateway URL. Use --gateway-base-url (or --local for localhost:8400 development) for non-interactive installs.
+Installing against a private/self-hosted gateway is its own flow: "pennyrouter install --private-gateway"
+asks for the gateway URL and your email, mints your key on that gateway, and skips the hosted browser
+login entirely. Pass them up front to run it unattended: --private-gateway URL --email you@example.com.
+--gateway-base-url URL takes the same path. If your administrator already issued you a key, pass
+--private-key pr-... and no email is asked for.
 
-A private gateway keeps its own keys, so the key from the browser login does not work there. Whenever
-you point install at one — with --gateway-base-url or by entering a URL at that prompt — you must also
-supply the key your PennyRouter administrator issued you: paste it when asked, or pass --private-key pr-...
+Self-service keys only work where the operator enabled them (PENNYROUTER_OPEN_PROVISIONING on the
+gateway); otherwise install says so and you need an administrator-issued --private-key.
 
 Install and update both register the Threads MCP server with Claude Code and Codex (--no-mcp to
 skip a run). Run "pennyrouter mcp install" if you skipped it or had to rename a conflicting
@@ -2227,6 +2302,8 @@ Examples:
   npx pennyrouter install --harness codex --openai-api-key <key>
   npx pennyrouter install --harness claude-code --proxy-base-url https://proxy.example.com --proxy-api-key <key>
   npx pennyrouter install --openrouter-api-key <key>
+  npx pennyrouter install --private-gateway
+  npx pennyrouter install --private-gateway https://gateway.example.com --email you@example.com
   npx pennyrouter install --gateway-base-url https://gateway.internal.example.com --private-key pr-...
   npx pennyrouter auth anthropic
   npx pennyrouter install --all

package/src/cli.test.js

@@ -269,3 +269,39 @@ test("--config leaves the hosted gateway alone when no private gateway is given"
     },
   );
 });
+
+// --private-gateway is its own install path: it never opens the hosted browser claim, so the
+// URL and email it needs must either be supplied or prompted for. Non-interactive runs can do
+// neither, and must say which piece is missing rather than failing later at the gateway.
+test("--private-gateway requires a gateway URL when it cannot prompt", async () => {
+  await assert.rejects(
+    () => captureLogs(() => main(["install", "--private-gateway", "--yes", "--harness", "claude-code"])),
+    /needs the gateway URL/,
+  );
+});
+
+test("--private-gateway requires an email when it cannot prompt", async () => {
+  await assert.rejects(
+    () => captureLogs(() => main([
+      "install", "--private-gateway", "https://gateway.example.com", "--yes", "--harness", "claude-code",
+    ])),
+    /needs an email/,
+  );
+});
+
+// An admin-issued key stands in for the email, so this must not ask for one.
+test("--private-key satisfies --private-gateway without an email", async () => {
+  const logs = await captureLogs(() => main([
+    "install", "--private-gateway=https://gateway.example.com", "--private-key", "pr-test",
+    "--yes", "--harness", "claude-code", "--dry-run",
+  ]));
+  assert.match(logs.join("\n"), /Serving gateway: https:\/\/gateway\.example\.com/);
+});
+
+// A bare --private-gateway must not swallow the following flag as its optional URL.
+test("--private-gateway does not consume a following flag as its URL", async () => {
+  await assert.rejects(
+    () => captureLogs(() => main(["install", "--private-gateway", "--yes", "--harness", "claude-code"])),
+    /needs the gateway URL/,
+  );
+});

package/src/harnesses/cline.js

@@ -51,11 +51,13 @@ export const clineHarness = {
     };
   },
 
-  async uninstall() {
+  // The record carries the base URL this install actually wrote, so a private/self-hosted
+  // gateway is named here instead of the hosted default the user never configured.
+  async uninstall(record) {
     console.log("");
     console.log("Cline manual uninstall");
     console.log("  Open Cline settings in VS Code and remove or replace the PennyRouter OpenAI Compatible provider:");
-    console.log("  - Base URL: https://api.pennyrouter.com/v1");
+    console.log(`  - Base URL: ${record?.changes?.base_url || "https://api.pennyrouter.com/v1"}`);
     console.log("  - API Key: pr-...");
     console.log("  - Model ID: pennyrouter/auto");
   },

package/src/harnesses/codegpt.js

@@ -50,11 +50,13 @@ export const codeGptHarness = {
     };
   },
 
-  async uninstall() {
+  // The record carries the base URL this install actually wrote, so a private/self-hosted
+  // gateway is named here instead of the hosted default the user never configured.
+  async uninstall(record) {
     console.log("");
     console.log("JetBrains CodeGPT manual uninstall");
     console.log("  Open CodeGPT settings and remove or replace the PennyRouter provider:");
-    console.log("  - Base URL: https://api.pennyrouter.com/v1");
+    console.log(`  - Base URL: ${record?.changes?.base_url || "https://api.pennyrouter.com/v1"}`);
     console.log("  - API Key: pr-...");
     console.log("  - Model: pennyrouter/auto");
   },

package/src/harnesses/codex.js

@@ -37,6 +37,7 @@ export const codexHarness = {
       apiKey,
       gatewayBaseUrl,
       subscriptionAuth,
+      surface: "codex-terminal",
     });
 
     await atomicWrite(CONFIG_PATH, next);
@@ -98,7 +99,10 @@ export async function detectCodexChatgptAuth() {
  * x-pennyrouter-key header authenticates the account to our gateway. In Penny-only mode
  * the pr- key is the provider bearer, matching the isolated probe's existing behavior.
  */
-export function renderCodexConfig(text, { apiKey, gatewayBaseUrl, subscriptionAuth }) {
+export function renderCodexConfig(
+  text,
+  { apiKey, gatewayBaseUrl, subscriptionAuth, surface = "codex-terminal" },
+) {
   const clean = removeManagedCodexConfig(text, { removeRootProvider: true }).trimEnd();
   if (new RegExp(`^\\s*\\[model_providers\\.${escapeRegex(PROVIDER_ID)}\\]\\s*$`, "m").test(clean)) {
     throw new Error(
@@ -111,9 +115,12 @@ export function renderCodexConfig(text, { apiKey, gatewayBaseUrl, subscriptionAu
   const authLines = subscriptionAuth
     ? [
         "requires_openai_auth = true",
-        `http_headers = { "x-pennyrouter-key" = ${escapedKey} }`,
+        `http_headers = { "x-pennyrouter-key" = ${escapedKey}, "x-pennyrouter-harness" = "codex", "x-pennyrouter-surface" = ${tomlString(surface)} }`,
       ]
-    : [`experimental_bearer_token = ${escapedKey}`];
+    : [
+        `experimental_bearer_token = ${escapedKey}`,
+        `http_headers = { "x-pennyrouter-harness" = "codex", "x-pennyrouter-surface" = ${tomlString(surface)} }`,
+      ];
   const block = [
     MANAGED_START,
     `model_provider = "${PROVIDER_ID}"`,

package/src/harnesses/codex.test.js

@@ -29,7 +29,9 @@ function testSubscriptionProviderIsRootSafe() {
   assert.ok(next.includes('[model_providers.pennyrouter]'));
   assert.ok(next.includes('base_url = "http://localhost:8400/v1"'));
   assert.ok(next.includes("requires_openai_auth = true"));
-  assert.ok(next.includes('http_headers = { "x-pennyrouter-key" = "pr-test-secret" }'));
+  assert.ok(next.includes('"x-pennyrouter-key" = "pr-test-secret"'));
+  assert.ok(next.includes('"x-pennyrouter-harness" = "codex"'));
+  assert.ok(next.includes('"x-pennyrouter-surface" = "codex-terminal"'));
   assert.ok(!next.includes("experimental_bearer_token"));
   assert.equal((next.match(/# --- PennyRouter managed Codex provider ---/g) || []).length, 1);
 }
@@ -51,6 +53,7 @@ function testLegacyMigrationAndIdempotence() {
   assert.ok(!once.includes("openai_base_url"));
   assert.ok(!once.includes("openai_api_key"));
   assert.ok(once.includes('experimental_bearer_token = "pr-new"'));
+  assert.ok(once.includes('"x-pennyrouter-surface" = "codex-terminal"'));
   assert.ok(!once.includes("requires_openai_auth"));
 }
 

package/src/install-manifest.json

@@ -107,7 +107,7 @@
   },
   "advanced": {
     "title": "Private PennyRouter gateway",
-    "description": "Route through a private PennyRouter gateway if supplied by your IT team.",
+    "description": "Route through your organization's PennyRouter gateway. Enter your email to get a key from it, or paste one your IT team issued you.",
     "fields": [
       {
         "config_key": "gatewayBaseUrl",
@@ -116,9 +116,15 @@
         "placeholder": "https://gateway.example.com",
         "requires_https": true
       },
+      {
+        "config_key": "email",
+        "label": "Your email",
+        "secret": false,
+        "placeholder": "you@example.com"
+      },
       {
         "config_key": "privateKey",
-        "label": "Private gateway key",
+        "label": "Private gateway key (if issued)",
         "secret": true,
         "placeholder": "pr-...",
         "prefix": "pr-"

package/src/launch.js

@@ -295,11 +295,11 @@ export function renderCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth }) {
   const authLines = subscriptionAuth
     ? [
         "requires_openai_auth = true",
-        'env_http_headers = { "x-pennyrouter-key" = "PENNYROUTER_API_KEY", "x-pennyrouter-title-session" = "PENNYROUTER_TITLE_SESSION_ID", "x-pennyrouter-harness" = "codex" }',
+        'env_http_headers = { "x-pennyrouter-key" = "PENNYROUTER_API_KEY", "x-pennyrouter-title-session" = "PENNYROUTER_TITLE_SESSION_ID", "x-pennyrouter-harness" = "codex", "x-pennyrouter-surface" = "codex-terminal" }',
       ]
     : [
         'env_key = "PENNYROUTER_API_KEY"',
-        'http_headers = { "x-pennyrouter-title-session" = "PENNYROUTER_TITLE_SESSION_ID", "x-pennyrouter-harness" = "codex" }',
+        'http_headers = { "x-pennyrouter-title-session" = "PENNYROUTER_TITLE_SESSION_ID", "x-pennyrouter-harness" = "codex", "x-pennyrouter-surface" = "codex-terminal" }',
       ];
   return [
     CODEX_PROFILE_MARKER,
@@ -545,6 +545,7 @@ export async function createCodexDesktopHome({ config, realHome }) {
       apiKey: config.api_key,
       gatewayBaseUrl: config.gateway_base_url,
       subscriptionAuth: Boolean(config.harnesses?.codex?.subscription_auth),
+      surface: "codex-desktop",
     }));
     await privateWrite(join(overlay, "config.toml"), desktopConfig);
     return overlay;
@@ -971,7 +972,9 @@ export async function runPenny(argv = process.argv.slice(2)) {
     stdio: "inherit",
     shell: process.platform === "win32",
   });
-  const stopTerminalTitle = ["claude", "codex", "opencode"].includes(harness)
+  // Claude Code owns its own terminal title updates while a turn is running. Do not
+  // compete with it from the parent process; Codex and OpenCode remain Penny-owned.
+  const stopTerminalTitle = ["codex", "opencode"].includes(harness)
     ? startPennyTerminalTitle({
         gatewayBaseUrl: config.gateway_base_url,
         apiKey: config.api_key,
@@ -1019,7 +1022,10 @@ async function runCodexDesktop(config, { logs = false, mode = "gateway" } = {})
   }
   if (mode === "native") {
     const child = spawn(codexDesktopExecutable(), [], {
-      cwd: process.cwd(),
+      // Desktop launches must not inherit a project directory. When PennyRouter itself is
+      // started from ~/Documents, that makes macOS attribute Codex's access to Documents to
+      // PennyRouter and trigger a protected-folder prompt.
+      cwd: homeDir(),
       env: process.env,
       stdio: logs ? "inherit" : "ignore",
       detached: !logs,
@@ -1042,7 +1048,8 @@ async function runCodexDesktop(config, { logs = false, mode = "gateway" } = {})
       "__codex-desktop-supervisor",
       overlay,
     ], {
-      cwd: process.cwd(),
+      // Keep the detached supervisor out of the caller's protected project directory too.
+      cwd: homeDir(),
       env: process.env,
       stdio: "ignore",
       detached: true,
@@ -1057,7 +1064,7 @@ async function runCodexDesktop(config, { logs = false, mode = "gateway" } = {})
 
 export async function runCodexDesktopSupervisor(overlay) {
   const child = spawn(codexDesktopExecutable(), [], {
-    cwd: process.cwd(),
+    cwd: homeDir(),
     env: { ...process.env, CODEX_HOME: overlay },
     stdio: "inherit",
     shell: process.platform === "win32",

package/src/launch.test.js

@@ -179,7 +179,8 @@ async function main() {
     const desktopConfig = fs.readFileSync(path.join(desktopHome, "config.toml"), "utf8");
     assert.match(desktopConfig, /^model_provider = "pennyrouter"/);
     assert.match(desktopConfig, /\[model_providers\.pennyrouter\]/);
-    assert.match(desktopConfig, /http_headers = \{ "x-pennyrouter-key" = "pr-super-secret" \}/);
+    assert.match(desktopConfig, /"x-pennyrouter-key" = "pr-super-secret"/);
+    assert.match(desktopConfig, /"x-pennyrouter-surface" = "codex-desktop"/);
     assert.equal(fs.readFileSync(path.join(home, ".codex", "config.toml"), "utf8"), nativeCodex);
     fs.rmSync(desktopHome, { recursive: true, force: true });
     const codexProfile = fs.readFileSync(codexLaunchProfilePath(), "utf8");
@@ -187,6 +188,7 @@ async function main() {
     assert.ok(codexProfile.includes("[tui]\nterminal_title = []"));
     assert.ok(codexProfile.includes('"x-pennyrouter-title-session" = "PENNYROUTER_TITLE_SESSION_ID"'));
     assert.ok(codexProfile.includes('"x-pennyrouter-harness" = "codex"'));
+    assert.ok(codexProfile.includes('"x-pennyrouter-surface" = "codex-terminal"'));
     assert.ok(!codexProfile.includes("pr-super-secret"));
     assert.ok(!rc.includes("pr-super-secret"));
 

package/src/session.js

@@ -71,6 +71,35 @@ export async function storeUpstreamCredential({ gatewayBaseUrl, apiKey, provider
   return response.json();
 }
 
+// Mint a key on a private gateway that has self-service provisioning enabled. The hosted
+// browser claim mints against pennyrouter.com's key store, which a private gateway does not
+// share, so this is the equivalent step for a self-hosted install. A gateway that has not
+// opted in answers 404, same as one running a build without the endpoint.
+export async function provisionPrivateGatewayKey({ gatewayBaseUrl, email, name }) {
+  const url = `${gatewayBaseUrl.replace(/\/+$/, "")}/v1/provision-key`;
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ email, ...(name ? { name } : {}) }),
+  });
+  if (!response.ok) {
+    let detail = "";
+    try {
+      detail = (await response.json())?.detail || "";
+    } catch {
+      // non-JSON body; fall through to status-only message
+    }
+    if (response.status === 404) {
+      throw new Error(
+        `${gatewayBaseUrl} does not offer self-service keys. Ask your PennyRouter `
+        + "administrator for one and pass `--private-key pr-...`.",
+      );
+    }
+    throw new Error(`Provisioning a key failed: HTTP ${response.status}${detail ? ` — ${detail}` : ""}`);
+  }
+  return response.json();
+}
+
 export async function storeAnthropicToken({ gatewayBaseUrl, apiKey, token }) {
   return storeUpstreamCredential({
     gatewayBaseUrl, apiKey, provider: "anthropic_oauth", token,