pennyrouter 0.3.10 → 0.3.12

package/package.json

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

package/src/cli.js

@@ -56,6 +56,10 @@ import {
   removePennyRuntime,
   savePennyConfig,
   setPennyHarnessEnabled,
+  DEFAULT_PROFILE,
+  listPennyProfiles,
+  activePennyProfile,
+  resolvePennyProfile,
 } from "./launch.js";
 
 const HARNESS_BY_ID = {
@@ -137,6 +141,11 @@ export async function main(argv = process.argv.slice(2)) {
     return;
   }
 
+  if (command === "profiles" || command === "profile") {
+    await profiles(flags);
+    return;
+  }
+
   if (command === "mcp") {
     // Bare `mcp` is the server itself, started by a harness over stdio. The subcommands are for
     // a person: registering after --no-mcp, retrying after a name conflict, or checking state.
@@ -151,6 +160,34 @@ export async function main(argv = process.argv.slice(2)) {
   throw new Error(`Unknown command "${command}". Run "pennyrouter help".`);
 }
 
+/**
+ * Show the stored credential sets, or make one active. The active profile is what
+ * `penny claude` uses when no --penny-profile / --private / --cloud flag is given.
+ */
+async function profiles(flags) {
+  const requested = flags.args[0];
+  const config = await loadPennyConfig();
+  const names = listPennyProfiles(config);
+  if (names.length === 0) {
+    console.log("No PennyRouter profiles configured. Run `npx pennyrouter install`.");
+    return;
+  }
+  if (requested) {
+    // Resolve before saving so an unknown name fails without changing anything.
+    const selected = resolvePennyProfile(config, requested);
+    await savePennyConfig({ ...selected, active_profile: requested });
+    console.log(`Active profile is now "${requested}" (${selected.gateway_base_url}).`);
+    return;
+  }
+  const active = activePennyProfile(config);
+  for (const name of names) {
+    const entry = config.profiles[name];
+    console.log(`${name === active ? "*" : " "} ${name}  ${entry.gateway_base_url}  ${maskKey(entry.api_key)}`);
+  }
+  console.log("");
+  console.log("Switch with: pennyrouter profiles <name>   (or penny claude --penny-profile <name>)");
+}
+
 function parseArgs(argv) {
   const command = argv[0] && !argv[0].startsWith("-") ? argv[0] : "install";
   const rest = command === argv[0] ? argv.slice(1) : argv;
@@ -193,6 +230,11 @@ function parseArgs(argv) {
     else if (arg === "--proxy-api-key") flags.proxyApiKey = rest[++i] || "";
     else if (arg.startsWith("--proxy-api-key=")) flags.proxyApiKey = arg.slice("--proxy-api-key=".length);
     else if (arg.startsWith("--openrouter-api-key=")) flags.openrouterApiKey = arg.slice("--openrouter-api-key=".length);
+    // --profile names which stored credential set this install writes to. Defaulted below
+    // from the install shape, so a private-gateway install lands in "private" without
+    // clobbering the cloud credentials that `penny claude` uses by default.
+    else if (arg === "--profile") flags.profile = rest[++i] || "";
+    else if (arg.startsWith("--profile=")) flags.profile = arg.slice("--profile=".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
@@ -253,6 +295,10 @@ function parseArgs(argv) {
 
   if (flags.configPath) applyConfigFile(flags);
 
+  // A self-hosted gateway is a distinct identity with its own key store, so give it its own
+  // profile unless one was named. Hosted installs keep the default profile.
+  if (!flags.profile) flags.profile = flags.privateGateway ? "private" : DEFAULT_PROFILE;
+
   return { command, flags };
 }
 
@@ -357,7 +403,7 @@ async function authProvider(flags) {
   }
 
   if (flags.forget) {
-    const launchConfig = await loadPennyConfig();
+    const launchConfig = await loadPennyConfig({ profile: flags.profile });
     const pennyKey = flags.pennyKey || launchConfig.api_key || await readClaudeCodePennyRouterKey();
     if (!pennyKey) {
       throw new Error(
@@ -410,7 +456,7 @@ async function authProvider(flags) {
     return;
   }
 
-  const launchConfig = await loadPennyConfig();
+  const launchConfig = await loadPennyConfig({ profile: flags.profile });
   const pennyKey = flags.pennyKey || launchConfig.api_key || await readClaudeCodePennyRouterKey();
   if (!pennyKey) {
     throw new Error(
@@ -442,6 +488,7 @@ async function authProvider(flags) {
     gatewayBaseUrl,
     subscriptionAuth: true,
     models: CLAUDE_CODE_MODELS,
+    profile: flags.profile,
   });
   let record = existingRecord || {
     harness: "claude-code",
@@ -620,7 +667,7 @@ export async function install(flags = {}) {
   let gatewayBaseUrl;
 
   if (needsAuth.length === 0) {
-    const launchConfig = await loadPennyConfig();
+    const launchConfig = await loadPennyConfig({ profile: flags.profile });
     const globalAuth = await readClaudeCodeGatewayAuth();
     const apiKey = flags.pennyKey || launchConfig.api_key || globalAuth.apiKey;
     if (!apiKey) {
@@ -642,7 +689,16 @@ export async function install(flags = {}) {
     // 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 launchConfig = await loadPennyConfig({ profile: flags.profile });
+    const globalAuth = await readClaudeCodeGatewayAuth();
+    const storedGateway = launchConfig.gateway_base_url || globalAuth.gatewayBaseUrl;
+    const storedKey = storedGateway && sameGatewayBaseUrl(gatewayBaseUrl, storedGateway)
+      ? (launchConfig.api_key || globalAuth.apiKey)
+      : null;
+    claim = {
+      api_key: await obtainPrivateGatewayKey(flags, gatewayBaseUrl, storedKey),
+      gateway_base_url: gatewayBaseUrl,
+    };
 
     const claudeProviders = await selectClaudeFundingProviders(flags, needsAuth);
     const codexProviders = await selectCodexFundingProviders(flags, needsAuth);
@@ -661,48 +717,86 @@ export async function install(flags = {}) {
       }));
     }
   } else {
-    const session = await createCliSession({
-      appUrl: flags.appUrl || APP_URL,
-      harnesses: selected.map((harness) => harness.id),
-      accountMode: "existing",
-    });
+    // Re-running the ordinary installer should refresh local harness configuration, not mint
+    // another machine key. Reuse a key already saved for this same gateway; an explicit gateway
+    // URL still wins, and a URL change deliberately falls through to fresh authorization.
+    const launchConfig = await loadPennyConfig({ profile: flags.profile });
+    const globalAuth = await readClaudeCodeGatewayAuth();
+    const existingApiKey = flags.pennyKey || launchConfig.api_key || globalAuth.apiKey;
+    const existingGateway = launchConfig.gateway_base_url || globalAuth.gatewayBaseUrl
+      || DEFAULT_GATEWAY_BASE_URL;
+    const requestedGateway = flags.gatewayBaseUrl || existingGateway;
+    const reusableKey = existingApiKey
+      && sameGatewayBaseUrl(requestedGateway, existingGateway)
+      ? existingApiKey
+      : null;
+
+    if (reusableKey) {
+      gatewayBaseUrl = existingGateway;
+      claim = { api_key: reusableKey, gateway_base_url: gatewayBaseUrl };
+      console.log(`Using existing PennyRouter key for ${gatewayBaseUrl}.`);
+      console.log("");
 
-    console.log("Opening your browser to log in and authorize this machine with your PennyRouter account...");
-    console.log(`If your browser did not open, visit:\n${session.authorize_url}`);
-    if (!flags.noBrowser) openBrowser(session.authorize_url);
-    console.log("");
-    console.log("Waiting for approval...");
+      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);
 
-    claim = await pollForKey(session);
-    console.log(`Authorized. Received key ${maskKey(claim.api_key)}.`);
-    console.log("");
+      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,
+        harnesses: selected.map((harness) => harness.id),
+        accountMode: "existing",
+      });
 
-    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);
-    gatewayBaseUrl = flags.gatewayBaseUrl || claim.gateway_base_url;
-    if (flags.gatewayBaseUrl) {
-      const normalized = normalizeGatewayBaseUrl(flags.gatewayBaseUrl);
-      if (!normalized) {
-        throw new Error(
-          `--gateway-base-url "${flags.gatewayBaseUrl}" is not a usable URL. Use a host like `
-          + "localhost:8400 or https://gateway.example.com.",
-        );
+      console.log("Opening your browser to log in and authorize this machine with your PennyRouter account...");
+      console.log(`If your browser did not open, visit:\n${session.authorize_url}`);
+      if (!flags.noBrowser) openBrowser(session.authorize_url);
+      console.log("");
+      console.log("Waiting for approval...");
+
+      claim = await pollForKey(session);
+      console.log(`Authorized. Received key ${maskKey(claim.api_key)}.`);
+      console.log("");
+
+      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);
+      gatewayBaseUrl = flags.gatewayBaseUrl || claim.gateway_base_url;
+      if (flags.gatewayBaseUrl) {
+        const normalized = normalizeGatewayBaseUrl(flags.gatewayBaseUrl);
+        if (!normalized) {
+          throw new Error(
+            `--gateway-base-url "${flags.gatewayBaseUrl}" is not a usable URL. Use a host like `
+            + "localhost:8000 or https://gateway.example.com.",
+          );
+        }
+        gatewayBaseUrl = normalized;
       }
-      gatewayBaseUrl = normalized;
-    }
 
-    for (const credential of funding.credentials) {
-      await withGatewayContext(gatewayBaseUrl, () => storeUpstreamCredential({
-        gatewayBaseUrl,
-        apiKey: claim.api_key,
-        provider: credential.provider,
-        token: credential.token,
-        metadata: credential.metadata,
-      }));
+      for (const credential of funding.credentials) {
+        await withGatewayContext(gatewayBaseUrl, () => storeUpstreamCredential({
+          gatewayBaseUrl,
+          apiKey: claim.api_key,
+          provider: credential.provider,
+          token: credential.token,
+          metadata: credential.metadata,
+        }));
+      }
     }
   }
 
@@ -751,6 +845,7 @@ export async function install(flags = {}) {
             ? claudeSubscriptionAuth
             : codexSubscriptionAuth,
           models: harness.id === "claude-code" ? CLAUDE_CODE_MODELS : null,
+          profile: flags.profile,
         });
       }
 
@@ -926,7 +1021,7 @@ async function resolvePrivateGatewayUrl(flags) {
 /* 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) {
+async function obtainPrivateGatewayKey(flags, gatewayBaseUrl, existingApiKey = null) {
   const issued = (flags.privateKey || "").trim();
   if (issued) {
     if (!issued.startsWith("pr-")) {
@@ -937,6 +1032,12 @@ async function obtainPrivateGatewayKey(flags, gatewayBaseUrl) {
     return issued;
   }
 
+  if (existingApiKey) {
+    console.log(`Using existing PennyRouter key for ${gatewayBaseUrl}.`);
+    console.log("");
+    return existingApiKey;
+  }
+
   let email = (flags.email || "").trim();
   if (!email) {
     // A shared --config file names the gateway but not who is installing, so the email is
@@ -985,6 +1086,12 @@ function normalizeGatewayBaseUrl(raw) {
   return withScheme.replace(/\/+$/, "");
 }
 
+function sameGatewayBaseUrl(left, right) {
+  const normalizedLeft = normalizeGatewayBaseUrl(left);
+  const normalizedRight = normalizeGatewayBaseUrl(right);
+  return Boolean(normalizedLeft && normalizedRight && normalizedLeft === normalizedRight);
+}
+
 /* A gateway that is unreachable (wrong host, wrong port, not running) surfaces from fetch() as
    an opaque "fetch failed" with no status. Name the gateway we could not reach so the user knows
    which URL to fix. Real HTTP errors carry their own message and pass through untouched. */
@@ -1110,7 +1217,7 @@ async function update(flags) {
     return;
   }
 
-  const launchConfig = await loadPennyConfig();
+  const launchConfig = await loadPennyConfig({ profile: flags.profile });
   const globalAuth = await readClaudeCodeGatewayAuth();
   const apiKey = flags.pennyKey || launchConfig.api_key || globalAuth.apiKey;
   const gatewayBaseUrl = flags.gatewayBaseUrl
@@ -1173,6 +1280,7 @@ async function update(flags) {
             ? claudeSubscriptionAuth
             : codexSubscriptionAuth,
           models: record.harness === "claude-code" ? CLAUDE_CODE_MODELS : null,
+          profile: flags.profile,
         });
       }
 
@@ -2281,6 +2389,7 @@ Usage:
   pennyrouter enable [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes]
   pennyrouter uninstall [--harness ${SUPPORTED_HARNESS_IDS}] [--all] [--yes] [--forget-token]
   pennyrouter status
+  pennyrouter profiles [name]
   pennyrouter mcp install|uninstall|status [--harness claude-code,codex]
 
 Installing against a private/self-hosted gateway is its own flow: "pennyrouter install --private-gateway"
@@ -2289,6 +2398,16 @@ login entirely. Pass them up front to run it unattended: --private-gateway URL -
 --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.
 
+Credentials are stored in named profiles, so one machine can hold both a cloud and a private
+gateway identity at once. A --private-gateway/--gateway-base-url install writes to the "private"
+profile and a hosted install to "cloud"; pass --profile NAME to choose another. Nothing is
+overwritten when you install the second one.
+
+  pennyrouter profiles                 list them (* marks the active one)
+  pennyrouter profiles private         make "private" the default for bare penny claude
+  penny claude --private               launch this one session against the private gateway
+  penny codex --penny-profile lab      any profile by name; also --cloud
+
 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.
 
@@ -2323,6 +2442,8 @@ Examples:
   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 profiles
+  npx pennyrouter profiles private
   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

package/src/launch.js

@@ -98,9 +98,18 @@ export function claudeDesktopCredentialHelperPath() {
   );
 }
 
-export function codexLaunchProfilePath() {
+/**
+ * Codex reads its provider settings from a file on disk rather than the environment, so
+ * each Penny profile needs its own file and its own Codex profile name. Without that,
+ * `penny codex --private` would launch against whichever gateway was written last.
+ */
+export function codexLaunchProfilePath(profile = DEFAULT_PROFILE) {
   const codexHome = process.env.CODEX_HOME || join(homeDir(), ".codex");
-  return join(codexHome, "pennyrouter.config.toml");
+  return join(codexHome, `pennyrouter-${profile}.config.toml`);
+}
+
+export function codexProfileName(profile = DEFAULT_PROFILE) {
+  return `pennyrouter-${profile}`;
 }
 
 export function claudeUserSkillPath() {
@@ -122,15 +131,77 @@ async function executableWrite(path, text) {
   if (process.platform !== "win32") await chmod(path, 0o700);
 }
 
-export async function loadPennyConfig() {
-  return (await readJsonFile(pennyConfigPath(), null)) || {
+/**
+ * Credentials live in named profiles so one machine can hold both a cloud and a
+ * private-gateway identity. Each profile owns an api_key/gateway_base_url pair; the rest
+ * of the config (harnesses, PATH state, Claude Desktop state) is machine-wide.
+ */
+export const DEFAULT_PROFILE = "cloud";
+
+export function listPennyProfiles(config) {
+  return Object.keys(config.profiles || {});
+}
+
+export function activePennyProfile(config) {
+  return config.active_profile || DEFAULT_PROFILE;
+}
+
+/**
+ * Return `config` with the named profile's credentials projected onto `api_key` and
+ * `gateway_base_url`. Every consumer reads those two fields, so resolving here keeps the
+ * profile lookup in one place rather than threading a profile through each caller.
+ *
+ * An unconfigured machine resolves to a profile with no credentials rather than throwing:
+ * `install` has to run against a config that does not exist yet.
+ */
+export function resolvePennyProfile(config, name = null) {
+  const requested = name || activePennyProfile(config);
+  const profiles = config.profiles || {};
+  const entry = profiles[requested];
+  if (!entry) {
+    if (Object.keys(profiles).length === 0) return { ...config, profile: requested };
+    const known = Object.keys(profiles).join(", ");
+    throw new Error(`Unknown PennyRouter profile "${requested}". Available: ${known}.`);
+  }
+  return {
+    ...config,
+    profile: requested,
+    api_key: entry.api_key,
+    gateway_base_url: entry.gateway_base_url,
+  };
+}
+
+/** Write credentials into a named profile and make it active. */
+export function setPennyProfile(config, name, { apiKey, gatewayBaseUrl }) {
+  return {
+    ...config,
+    profiles: {
+      ...(config.profiles || {}),
+      [name]: { api_key: apiKey, gateway_base_url: gatewayBaseUrl },
+    },
+    active_profile: name,
+  };
+}
+
+export async function loadPennyConfig({ profile = null } = {}) {
+  const config = (await readJsonFile(pennyConfigPath(), null)) || {
     version: CONFIG_VERSION,
+    profiles: {},
     harnesses: {},
   };
+  return resolvePennyProfile(config, profile);
 }
 
+/**
+ * Persist a config. A resolved config carries the active profile's credentials on
+ * `api_key`/`gateway_base_url`; strip those before writing so a save after a load does not
+ * leave a stale duplicate of one profile's credentials at the top level.
+ */
 export async function savePennyConfig(config) {
   const next = { version: CONFIG_VERSION, ...config };
+  delete next.profile;
+  delete next.api_key;
+  delete next.gateway_base_url;
   await privateWrite(pennyConfigPath(), `${JSON.stringify(next, null, 2)}\n`);
   return next;
 }
@@ -699,8 +770,8 @@ async function writeClaudeUserSkill() {
   }
 }
 
-async function writeCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth }) {
-  const path = codexLaunchProfilePath();
+async function writeCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth, profile }) {
+  const path = codexLaunchProfilePath(profile);
   const existing = await readText(path, "");
   if (existing.trim() && !existing.startsWith(CODEX_PROFILE_MARKER)) {
     throw new Error(
@@ -715,10 +786,17 @@ export async function configurePennyHarness(harness, {
   gatewayBaseUrl,
   subscriptionAuth = false,
   models = null,
+  profile = null,
 }) {
-  const config = await loadPennyConfig();
-  config.gateway_base_url = gatewayBaseUrl;
+  const loaded = await loadPennyConfig();
+  const config = setPennyProfile(loaded, profile || activePennyProfile(loaded), {
+    apiKey,
+    gatewayBaseUrl,
+  });
+  // The rest of this function writes harness files from the credentials just stored, so
+  // project them for the local reads below.
   config.api_key = apiKey;
+  config.gateway_base_url = gatewayBaseUrl;
   config.harnesses ||= {};
   if (harness === "claude-code") {
     await writeClaudeUserSkill();
@@ -729,7 +807,11 @@ export async function configurePennyHarness(harness, {
       models: models || {},
     };
   } else if (harness === "codex") {
-    await writeCodexLaunchProfile({ gatewayBaseUrl, subscriptionAuth });
+    await writeCodexLaunchProfile({
+      gatewayBaseUrl,
+      subscriptionAuth,
+      profile: config.active_profile,
+    });
     config.harnesses.codex = {
       enabled: true,
       subscription_auth: Boolean(subscriptionAuth),
@@ -769,9 +851,13 @@ export async function removePennyHarness(harness) {
       });
     }
   } else if (harness === "codex") {
-    const existing = await readText(codexLaunchProfilePath(), "");
-    if (existing.startsWith(CODEX_PROFILE_MARKER)) {
-      await unlink(codexLaunchProfilePath()).catch((error) => {
+    // Remove the file for every profile: `remove codex` uninstalls the harness, not one
+    // credential set.
+    for (const name of listPennyProfiles(config)) {
+      const path = codexLaunchProfilePath(name);
+      const existing = await readText(path, "");
+      if (!existing.startsWith(CODEX_PROFILE_MARKER)) continue;
+      await unlink(path).catch((error) => {
         if (error.code !== "ENOENT") throw error;
       });
     }
@@ -826,6 +912,38 @@ export async function removePennyRuntime() {
   });
 }
 
+/**
+ * Split Penny's own flags out of the harness argument list. `--penny-profile` (and the
+ * `--private`/`--cloud` shorthands) select which stored credential to launch with; the
+ * harnesses have no such flags, so they must not be forwarded. Everything after a bare
+ * `--` belongs to the harness and is left untouched.
+ */
+export function extractProfileArgs(args) {
+  const rest = [];
+  let profile = null;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--") {
+      rest.push(...args.slice(i));
+      break;
+    }
+    if (arg === "--penny-profile") {
+      profile = args[++i];
+      if (!profile) throw new Error("--penny-profile requires a profile name.");
+    } else if (arg.startsWith("--penny-profile=")) {
+      profile = arg.slice("--penny-profile=".length);
+      if (!profile) throw new Error("--penny-profile requires a profile name.");
+    } else if (arg === "--private") {
+      profile = "private";
+    } else if (arg === "--cloud") {
+      profile = "cloud";
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { profile, args: rest };
+}
+
 function assertNoConflictingArgs(harness, args) {
   if (harness === "claude" && args.some((arg) => arg === "--settings" || arg.startsWith("--settings="))) {
     throw new Error("penny claude manages --settings; remove that flag or run native claude.");
@@ -889,7 +1007,11 @@ export function buildPennyInvocation(harness, args, config) {
     // identity. Give both sides a launch-local join token so title warmth cannot bleed between
     // two Codex TUIs using the same Penny key.
     env.PENNYROUTER_TITLE_SESSION_ID = randomUUID();
-    return { command: "codex", args: ["--profile", "pennyrouter", ...args], env };
+    return {
+      command: "codex",
+      args: ["--profile", codexProfileName(config.profile), ...args],
+      env,
+    };
   }
   if (harness === "opencode") {
     env.PENNYROUTER_TITLE_SESSION_ID = randomUUID();
@@ -908,13 +1030,16 @@ async function waitForChild(child) {
 export async function runPenny(argv = process.argv.slice(2)) {
   const harness = argv[0];
   if (!harness || harness === "help" || harness === "--help" || harness === "-h") {
-    console.log("Usage: penny <claude|codex|opencode> [native arguments...]");
+    console.log("Usage: penny <claude|codex|opencode> [--penny-profile <name>] [native arguments...]");
+    console.log("       --private / --cloud select the like-named profile.");
     return 0;
   }
   if (!["claude", "codex", "opencode"].includes(harness)) {
     throw new Error(`Unknown harness "${harness}". Try penny claude, penny codex, or penny opencode.`);
   }
-  const config = await loadPennyConfig();
+  const selection = extractProfileArgs(argv.slice(1));
+  argv = [harness, ...selection.args];
+  const config = await loadPennyConfig({ profile: selection.profile });
   if (harness === "claude" && argv[1]?.toLowerCase() === "desktop") {
     const option = argv[2]?.toLowerCase();
     if (option === "--restore" || option === "restore") {

package/src/launch.test.js

@@ -29,6 +29,12 @@ import {
   restoreClaudeDesktopProfile,
   selectClaudeDesktopNativeMode,
   renderCodexLaunchProfile,
+  extractProfileArgs,
+  resolvePennyProfile,
+  setPennyProfile,
+  savePennyConfig,
+  listPennyProfiles,
+  activePennyProfile,
 } from "./launch.js";
 import { claudeCodeHarness } from "./harnesses/claude-code.js";
 
@@ -216,7 +222,7 @@ async function main() {
     assert.deepEqual(normalPrompt.args.slice(-2), ["proxy", "please"]);
 
     const codex = buildPennyInvocation("codex", ["resume", "--last"], config);
-    assert.deepEqual(codex.args, ["--profile", "pennyrouter", "resume", "--last"]);
+    assert.deepEqual(codex.args, ["--profile", "pennyrouter-cloud", "resume", "--last"]);
     assert.equal(codex.env.PENNYROUTER_API_KEY, "pr-super-secret");
     const opencode = buildPennyInvocation("opencode", ["--continue"], config);
     assert.equal(opencode.env.PENNYROUTER_API_KEY, "pr-super-secret");
@@ -286,9 +292,67 @@ async function main() {
     fs.rmSync(root, { recursive: true, force: true });
   }
 
+  await testProfiles();
   console.log("launch.test.js: all checks passed");
 }
 
+async function testProfiles() {
+  // Penny's own flags are consumed here and must never reach the harness; everything
+  // after a bare `--` is the harness's to interpret, including a literal --private.
+  assert.deepEqual(extractProfileArgs(["--resume", "abc"]), {
+    profile: null, args: ["--resume", "abc"],
+  });
+  assert.deepEqual(extractProfileArgs(["--private", "--resume", "abc"]), {
+    profile: "private", args: ["--resume", "abc"],
+  });
+  assert.deepEqual(extractProfileArgs(["--cloud"]), { profile: "cloud", args: [] });
+  assert.deepEqual(extractProfileArgs(["--penny-profile", "lab", "-c"]), {
+    profile: "lab", args: ["-c"],
+  });
+  assert.deepEqual(extractProfileArgs(["--penny-profile=lab"]), {
+    profile: "lab", args: [],
+  });
+  assert.deepEqual(extractProfileArgs(["--", "--private"]), {
+    profile: null, args: ["--", "--private"],
+  });
+  assert.throws(() => extractProfileArgs(["--penny-profile"]), /requires a profile name/);
+
+  const config = setPennyProfile(
+    setPennyProfile({ harnesses: {} }, "cloud", {
+      apiKey: "pr-cloud", gatewayBaseUrl: "https://api.pennyrouter.com",
+    }),
+    "private",
+    { apiKey: "pr-private", gatewayBaseUrl: "http://localhost:8400" },
+  );
+  // The most recent write is active, and each profile keeps its own credentials.
+  assert.equal(activePennyProfile(config), "private");
+  assert.deepEqual(listPennyProfiles(config).sort(), ["cloud", "private"]);
+  assert.equal(resolvePennyProfile(config).api_key, "pr-private");
+  assert.equal(resolvePennyProfile(config, "cloud").api_key, "pr-cloud");
+  assert.equal(
+    resolvePennyProfile(config, "cloud").gateway_base_url,
+    "https://api.pennyrouter.com",
+  );
+  assert.throws(() => resolvePennyProfile(config, "nope"), /Unknown PennyRouter profile/);
+
+  // A resolved config must not persist one profile's credentials at the top level,
+  // where they would shadow whichever profile is selected on the next load.
+  const written = await savePennyConfig(resolvePennyProfile(config, "cloud"));
+  assert.equal(written.api_key, undefined);
+  assert.equal(written.gateway_base_url, undefined);
+  assert.equal(written.profiles.private.api_key, "pr-private");
+  const reloaded = await loadPennyConfig({ profile: "private" });
+  assert.equal(reloaded.api_key, "pr-private");
+
+  // Each profile launches Codex against its own on-disk provider file.
+  const invocation = buildPennyInvocation(
+    "codex", [], { ...resolvePennyProfile(config, "private"), harnesses: { codex: { enabled: true } } },
+  );
+  assert.deepEqual(invocation.args, ["--profile", "pennyrouter-private"]);
+  assert.ok(codexLaunchProfilePath("private").endsWith("pennyrouter-private.config.toml"));
+  assert.notEqual(codexLaunchProfilePath("private"), codexLaunchProfilePath("cloud"));
+}
+
 main().catch((error) => {
   console.error(error);
   process.exit(1);