@runuai/host 0.8.9 → 0.8.11

package/lib/agents/grok.ts

@@ -148,6 +148,11 @@ export class GrokSession implements AgentSession {
 
   private buildArgs(prompt: string): string[] {
     const args = ["exec", "-i", "-u", "node"];
+    // Host-resident API key (pasted in the engines panel, ADR-015): forward
+    // name-only — docker takes the value from the client env, keeping the
+    // secret out of argv. Subscription logins need nothing here (task-up
+    // copies ~/.grok into the container instead).
+    if (process.env.XAI_API_KEY) args.push("-e", "XAI_API_KEY");
     for (const [k, v] of Object.entries(this.agentEnv)) {
       args.push("-e", `${k}=${v}`);
     }
@@ -249,7 +254,8 @@ register({
   supportedModels: () => [...GROK_MODELS],
   defaultModel: GROK_DEFAULT_MODEL,
   supportedEfforts: () => [...GROK_EFFORTS],
-  available: () => existsSync(grokAuthPath()),
+  available: () =>
+    existsSync(grokAuthPath()) || Boolean(process.env.XAI_API_KEY),
   create: async ({ taskId, agent, containerName, systemPreamble, agentEnv }) =>
     new GrokSession({ taskId, agent, containerName, systemPreamble, agentEnv }),
 });

package/lib/engines.ts

@@ -3,11 +3,18 @@
  *
  * A single descriptor table for the AI coding engines the host can run
  * (Claude, Codex, Kimi, Grok, Cursor) plus the connect/disconnect/status logic
- * the local UI drives. This is the host-side twin of the desktop's
- * `apps/host-desktop/src/llm.ts`, but it writes the `.env.local` the RUNNING
- * launchd/npm host reads (UAI_HOME) and sets `process.env` so a connect takes
- * effect WITHOUT a host restart — the adapters' `available()` and task-up's env
- * injection both read `process.env`.
+ * the local UI drives (the desktop app renders that same UI). It writes the
+ * `.env.local` the RUNNING launchd/npm host reads (UAI_HOME) and sets
+ * `process.env` so a connect takes effect WITHOUT a host restart — the
+ * adapters' `available()` and task-up's env injection both read `process.env`.
+ *
+ * CLI resolution: a host supervised by the desktop app (or launchd) inherits a
+ * minimal GUI PATH that lacks wherever the engine CLIs live (~/.local/bin,
+ * npm/nvm/asdf prefixes, Homebrew), so spawning a bare `claude`/`codex` would
+ * ENOENT even though the CLI is installed. We resolve binaries the way the
+ * owner's terminal would — well-known install dirs first, then the login
+ * shell's PATH (same trick as the desktop's docker.ts) — and spawn with that
+ * PATH so `#!/usr/bin/env node` shebangs resolve too.
  *
  * Three auth modes:
  *   - token-command  (Claude): `claude setup-token` prints a token to stdout;
@@ -17,6 +24,21 @@
  *                    writes a config file; success = that file appearing.
  *   - api-key        (Cursor): no command — persist a pasted CURSOR_API_KEY.
  *
+ * Besides its primary mode, an engine can accept a pasted API key as an
+ * alternative (`apiKeyHint`/`apiKeyUrl` in the catalog drive the UI):
+ *   - claude → ANTHROPIC_API_KEY (the adapter already forwards it; a pasted
+ *     `sk-ant-oat…` still lands in CLAUDE_CODE_OAUTH_TOKEN — classified by
+ *     prefix, so either credential works in either paste box).
+ *   - codex  → ~/.codex/auth.json `{"OPENAI_API_KEY": …}`, the same plaintext
+ *     file `codex login --with-api-key` writes. Written directly (not via the
+ *     CLI): task-up docker-cp's that FILE into containers, so a keychain-backed
+ *     CLI login would break task auth, and this works with no host CLI at all.
+ *   - grok   → XAI_API_KEY (documented pay-as-you-go fallback of the grok CLI;
+ *     the adapter forwards it into task containers).
+ *   - kimi   → none: Kimi Code reads keys only from its config.toml via the
+ *     interactive `/login`, never from the environment — so we don't offer a
+ *     paste box we can't honor.
+ *
  * Detection mirrors each adapter's `available()`: env/`.env.local` for
  * claude/cursor, a config file under the owner home for codex/kimi/grok.
  *
@@ -25,7 +47,11 @@
  * the real filesystem or spawning anything.
  */
 
-import { spawn as nodeSpawn, type ChildProcess } from "node:child_process";
+import {
+  execFile as nodeExecFile,
+  spawn as nodeSpawn,
+  type ChildProcess,
+} from "node:child_process";
 import {
   chmodSync,
   existsSync,
@@ -51,6 +77,10 @@ export interface EngineCatalogEntry {
   notes: string | null;
   /** Where to mint an API key (api-key mode only). */
   getKeyUrl: string | null;
+  /** Placeholder for the pasted-API-key alternative; null = not supported. */
+  apiKeyHint: string | null;
+  /** Where to mint a key for the pasted-API-key alternative. */
+  apiKeyUrl: string | null;
 }
 
 interface EngineDescriptor {
@@ -58,6 +88,9 @@ interface EngineDescriptor {
   authMode: EngineAuthMode;
   notes: string;
   getKeyUrl?: string;
+  /** Pasted-API-key alternative (absent = login/token only, e.g. kimi). */
+  apiKeyHint?: string;
+  apiKeyUrl?: string;
 }
 
 /** Static descriptor table — the single source of truth for engine metadata. */
@@ -67,11 +100,15 @@ const DESCRIPTORS: Record<EngineKind, EngineDescriptor> = {
     authMode: "token-command",
     notes:
       "Opens your browser to authorize Claude, then captures the token automatically.",
+    apiKeyHint: "sk-ant-…",
+    apiKeyUrl: "https://console.anthropic.com/settings/keys",
   },
   codex: {
     label: "Codex",
     authMode: "login-command",
     notes: "Opens your browser to sign in to your OpenAI Codex account.",
+    apiKeyHint: "sk-…",
+    apiKeyUrl: "https://platform.openai.com/api-keys",
   },
   kimi: {
     label: "Kimi Code",
@@ -84,6 +121,8 @@ const DESCRIPTORS: Record<EngineKind, EngineDescriptor> = {
     authMode: "login-command",
     notes:
       "Sign in with your xAI Grok subscription. Activates after the next image rebuild.",
+    apiKeyHint: "xai-…",
+    apiKeyUrl: "https://console.x.ai",
   },
   cursor: {
     label: "Cursor",
@@ -101,7 +140,11 @@ const ORDER: EngineKind[] = ["claude", "codex", "kimi", "grok", "cursor"];
 // ---------------------------------------------------------------------------
 
 /** How a login/token command is spawned. Tests provide a fake. */
-export type EngineSpawn = (command: string, args: string[]) => ChildProcess;
+export type EngineSpawn = (
+  command: string,
+  args: string[],
+  env: NodeJS.ProcessEnv,
+) => ChildProcess;
 
 export interface EngineSeams {
   /** Spawn a CLI, piping stdout/stderr. */
@@ -112,18 +155,53 @@ export interface EngineSeams {
   ownerHome: () => string;
   /** The live process env (adapters + task-up read creds from here). */
   procEnv: NodeJS.ProcessEnv;
+  /** PATH as the owner's login shell sees it (null when unprobeable). */
+  loginShellPath: () => Promise<string | null>;
+  /** System-wide bin dirs probed for engine CLIs (tests pin to []). */
+  systemBinDirs: string[];
 }
 
 function defaultSeams(): EngineSeams {
   return {
-    spawn: (command, args) =>
-      nodeSpawn(command, args, { stdio: ["ignore", "pipe", "pipe"] }),
+    spawn: (command, args, spawnEnv) =>
+      nodeSpawn(command, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        env: spawnEnv,
+      }),
     envLocalPath: () => join(env.uaiHome, ".env.local"),
     ownerHome: () => process.env.UAI_OWNER_HOME?.trim() || homedir(),
     procEnv: process.env,
+    loginShellPath: probeLoginShellPath,
+    systemBinDirs: ["/opt/homebrew/bin", "/usr/local/bin"],
   };
 }
 
+/**
+ * The PATH the owner's login shell exports. Runs `/usr/bin/env` (not
+ * `echo $PATH`) so the value is the real colon-joined exported PATH under any
+ * shell — fish's `$PATH` is a list and would echo space-joined — and takes the
+ * LAST `PATH=` line so profile echo noise can't spoof it. Null on any failure;
+ * callers fall back to the inherited PATH.
+ */
+function probeLoginShellPath(): Promise<string | null> {
+  return new Promise((resolve) => {
+    const shell = process.env.SHELL?.trim() || "/bin/zsh";
+    nodeExecFile(
+      shell,
+      ["-lc", "/usr/bin/env"],
+      { timeout: 8_000 },
+      (err, stdout) => {
+        if (err) return resolve(null);
+        const lines = String(stdout)
+          .split(/\r?\n/)
+          .filter((l) => l.startsWith("PATH="));
+        const last = lines[lines.length - 1];
+        resolve(last ? last.slice("PATH=".length).trim() || null : null);
+      },
+    );
+  });
+}
+
 function withDefaults(seams: Partial<EngineSeams>): EngineSeams {
   return { ...defaultSeams(), ...seams };
 }
@@ -132,7 +210,7 @@ function withDefaults(seams: Partial<EngineSeams>): EngineSeams {
 // Public catalog / status.
 // ---------------------------------------------------------------------------
 
-/** The static engine catalog (kind, label, authMode, notes, getKeyUrl). */
+/** The static engine catalog (kind, label, authMode, notes, key URLs). */
 export function engineCatalog(): EngineCatalogEntry[] {
   return ORDER.map((kind) => {
     const d = DESCRIPTORS[kind];
@@ -142,6 +220,8 @@ export function engineCatalog(): EngineCatalogEntry[] {
       authMode: d.authMode,
       notes: d.notes,
       getKeyUrl: d.getKeyUrl ?? null,
+      apiKeyHint: d.apiKeyHint ?? null,
+      apiKeyUrl: d.apiKeyUrl ?? null,
     };
   });
 }
@@ -183,9 +263,9 @@ export function isEngineKind(value: unknown): value is EngineKind {
 // ---------------------------------------------------------------------------
 
 export interface ConnectOptions {
-  /** api-key mode: the pasted key (Cursor). */
+  /** A pasted API key — primary for Cursor, alternative for claude/codex/grok. */
   apiKey?: string;
-  /** token-command manual fallback: a pasted token (Claude). */
+  /** token-command manual fallback: a pasted token or API key (Claude). */
   pastedToken?: string;
 }
 
@@ -207,21 +287,14 @@ export async function connectEngine(
   const s = withDefaults(seams);
   const d = DESCRIPTORS[kind];
 
-  if (d.authMode === "api-key") {
-    const key = (opts.apiKey ?? "").trim();
-    if (!key) return { ok: false, message: `Paste your ${d.label} API key.` };
-    if (/\s/.test(key) || key.length < 8) {
-      return {
-        ok: false,
-        message: "That doesn't look like an API key. Paste just the value.",
-      };
-    }
-    upsertEnvLocal("CURSOR_API_KEY", key, s);
-    return { ok: true, message: `${d.label} connected.` };
+  // A pasted API key connects without spawning anything — the only flow for
+  // api-key engines (Cursor), an alternative for the others.
+  if (d.authMode === "api-key" || opts.apiKey !== undefined) {
+    return saveApiKey(kind, d, opts.apiKey ?? "", s);
   }
 
   if (d.authMode === "token-command") {
-    // Manual paste fallback — accept a token without spawning the CLI.
+    // Manual paste fallback — accept a token (or API key) without spawning.
     if (opts.pastedToken !== undefined) {
       const token = opts.pastedToken.trim();
       if (!token) return { ok: false, message: "Paste a token." };
@@ -231,7 +304,15 @@ export async function connectEngine(
           message: "That doesn't look like a token. Paste just the value.",
         };
       }
-      upsertEnvLocal("CLAUDE_CODE_OAUTH_TOKEN", token, s);
+      // One paste box serves both credential kinds — classify by prefix so an
+      // `sk-ant-api…` platform key doesn't get stored as an OAuth token.
+      upsertEnvLocal(
+        token.startsWith("sk-ant-api")
+          ? "ANTHROPIC_API_KEY"
+          : "CLAUDE_CODE_OAUTH_TOKEN",
+        token,
+        s,
+      );
       return { ok: true, message: `${d.label} connected.` };
     }
     return runTokenCommand(kind, d.label, onLog, s);
@@ -240,6 +321,70 @@ export async function connectEngine(
   return runLoginCommand(kind, d.label, onLog, s);
 }
 
+/** Persist a pasted API key where the engine's adapter actually reads it. */
+function saveApiKey(
+  kind: EngineKind,
+  d: EngineDescriptor,
+  raw: string,
+  s: EngineSeams,
+): ConnectResult {
+  const key = raw.trim();
+  if (!key) return { ok: false, message: `Paste your ${d.label} API key.` };
+  if (/\s/.test(key) || key.length < 8) {
+    return {
+      ok: false,
+      message: "That doesn't look like an API key. Paste just the value.",
+    };
+  }
+  switch (kind) {
+    case "cursor":
+      upsertEnvLocal("CURSOR_API_KEY", key, s);
+      break;
+    case "claude":
+      // Accept either credential kind here too (see the paste fallback above).
+      upsertEnvLocal(
+        key.startsWith("sk-ant-oat") ? "CLAUDE_CODE_OAUTH_TOKEN" : "ANTHROPIC_API_KEY",
+        key,
+        s,
+      );
+      break;
+    case "grok":
+      // The grok CLI's documented pay-as-you-go fallback; the adapter forwards
+      // it into task containers.
+      upsertEnvLocal("XAI_API_KEY", key, s);
+      break;
+    case "codex":
+      writeCodexAuthJson(key, s);
+      break;
+    case "kimi":
+      return {
+        ok: false,
+        message:
+          "Kimi Code authenticates via subscription sign-in — it doesn't read API keys from the environment.",
+      };
+  }
+  return { ok: true, message: `${d.label} connected.` };
+}
+
+/**
+ * Write `~/.codex/auth.json` the way `codex login --with-api-key` does. We
+ * write the plaintext file directly (not via the CLI) because task-up
+ * docker-cp's this exact FILE into containers — a keychain-backed CLI login
+ * would leave nothing to copy — and it must work without a host codex CLI.
+ */
+function writeCodexAuthJson(key: string, s: EngineSeams): void {
+  const file = join(s.ownerHome(), ".codex", "auth.json");
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ OPENAI_API_KEY: key }, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    /* best effort */
+  }
+}
+
 /** Disconnect an engine: forget its credential (env line and/or config file). */
 export function disconnectEngine(
   kind: EngineKind,
@@ -256,6 +401,8 @@ export function disconnectEngine(
     removeEnvLocal("ANTHROPIC_AUTH_TOKEN", s);
     return;
   }
+  // grok can be connected via login (auth.json) OR a pasted key — drop both.
+  if (kind === "grok") removeEnvLocal("XAI_API_KEY", s);
   // login-command engines: remove the config file the adapter detects.
   try {
     rmSync(configPath(kind, s), { force: true });
@@ -299,9 +446,10 @@ function detect(kind: EngineKind, s: EngineSeams): boolean {
       );
     case "cursor":
       return envOrFileHas("CURSOR_API_KEY", s);
+    case "grok":
+      return existsSync(configPath(kind, s)) || envOrFileHas("XAI_API_KEY", s);
     case "codex":
     case "kimi":
-    case "grok":
       return existsSync(configPath(kind, s));
   }
 }
@@ -327,26 +475,103 @@ function configPath(kind: EngineKind, s: EngineSeams): string {
   return join(home, ".grok", "auth.json");
 }
 
-/** Resolve the login/token CLI binary — absolute for kimi/grok, else on PATH. */
-function resolveBin(kind: EngineKind, s: EngineSeams): string {
-  if (kind === "kimi") {
-    const local = join(s.ownerHome(), ".kimi-code", "bin", "kimi");
-    return existsSync(local) ? local : "kimi";
+/**
+ * Well-known install locations for an engine CLI — the dirs a GUI-launched
+ * host's minimal PATH misses. Home-relative entries resolve against the OWNER
+ * home (seam-injectable). The binary name equals the engine kind for all four
+ * CLI engines.
+ */
+function candidateBins(kind: EngineKind, s: EngineSeams): string[] {
+  const home = s.ownerHome();
+  const common = [join(home, ".local", "bin"), ...s.systemBinDirs];
+  switch (kind) {
+    case "claude":
+      // Native installer symlinks ~/.local/bin/claude (preferred); the older
+      // "local install" migration keeps a wrapper at ~/.claude/local/claude.
+      return [join(home, ".local", "bin"), join(home, ".claude", "local"), ...s.systemBinDirs].map(
+        (d) => join(d, "claude"),
+      );
+    case "codex":
+      return common.map((d) => join(d, "codex"));
+    case "kimi":
+      return [join(home, ".kimi-code", "bin"), ...common].map((d) =>
+        join(d, "kimi"),
+      );
+    case "grok":
+      return [join(home, ".grok", "bin"), ...common].map((d) => join(d, "grok"));
+    case "cursor":
+      return []; // api-key mode — never spawned
+  }
+}
+
+interface ResolvedBin {
+  /** Command to spawn — absolute when found, else the bare name. */
+  bin: string;
+  /** PATH for the child, augmented so nested lookups (node, git) resolve. */
+  path: string;
+}
+
+/**
+ * Find the engine CLI the way the owner's terminal would: well-known install
+ * dirs first (fast, no subprocess), then the login shell's PATH (sources the
+ * owner's profile — covers nvm/asdf/npm prefixes), else the bare name against
+ * the inherited PATH so a genuinely missing CLI still surfaces the friendly
+ * ENOENT "install it first" message.
+ */
+async function resolveEngineBin(
+  kind: EngineKind,
+  s: EngineSeams,
+): Promise<ResolvedBin> {
+  const inherited = s.procEnv.PATH ?? "";
+  for (const file of candidateBins(kind, s)) {
+    if (existsSync(file)) {
+      return { bin: file, path: prependPath([dirname(file)], inherited) };
+    }
   }
-  if (kind === "grok") {
-    const local = join(s.ownerHome(), ".grok", "bin", "grok");
-    return existsSync(local) ? local : "grok";
+  const login = await s.loginShellPath();
+  if (login) {
+    const dirs = login.split(":").filter(Boolean);
+    const dir = dirs.find((d) => existsSync(join(d, kind)));
+    // Found or not, hand the login PATH to the child — it is the environment
+    // where the CLI (and whatever it shells out to) is known to work.
+    return {
+      bin: dir ? join(dir, kind) : kind,
+      path: prependPath(dirs, inherited),
+    };
   }
-  // claude / codex are on PATH.
-  return kind;
+  return { bin: kind, path: inherited };
+}
+
+/** Prepend dirs to a colon-joined PATH, deduped, order-preserving. */
+function prependPath(prepend: string[], current: string): string {
+  const seen = new Set<string>();
+  return [...prepend, ...current.split(":")]
+    .filter((p) => p.length > 0 && !seen.has(p) && (seen.add(p), true))
+    .join(":");
 }
 
-function runTokenCommand(
+/** Resolve the CLI and spawn it with the augmented PATH. */
+async function spawnEngineCli(
+  kind: EngineKind,
+  args: string[],
+  s: EngineSeams,
+): Promise<ChildProcess> {
+  const { bin, path } = await resolveEngineBin(kind, s);
+  return s.spawn(bin, args, { ...s.procEnv, PATH: path });
+}
+
+async function runTokenCommand(
   kind: EngineKind,
   label: string,
   onLog: (line: string) => void,
   s: EngineSeams,
 ): Promise<ConnectResult> {
+  let child: ChildProcess;
+  try {
+    child = await spawnEngineCli(kind, ["setup-token"], s);
+  } catch (err) {
+    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+  }
   return new Promise((resolve) => {
     let settled = false;
     const done = (r: ConnectResult): void => {
@@ -355,13 +580,6 @@ function runTokenCommand(
         resolve(r);
       }
     };
-    let child: ChildProcess;
-    try {
-      child = s.spawn(resolveBin(kind, s), ["setup-token"]);
-    } catch (err) {
-      done({ ok: false, message: err instanceof Error ? err.message : String(err) });
-      return;
-    }
     let stdout = "";
     child.stdout?.on("data", (b: Buffer) => {
       const text = b.toString("utf8");
@@ -394,12 +612,18 @@ function runTokenCommand(
   });
 }
 
-function runLoginCommand(
+async function runLoginCommand(
   kind: EngineKind,
   label: string,
   onLog: (line: string) => void,
   s: EngineSeams,
 ): Promise<ConnectResult> {
+  let child: ChildProcess;
+  try {
+    child = await spawnEngineCli(kind, ["login"], s);
+  } catch (err) {
+    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+  }
   return new Promise((resolve) => {
     let settled = false;
     const done = (r: ConnectResult): void => {
@@ -408,13 +632,6 @@ function runLoginCommand(
         resolve(r);
       }
     };
-    let child: ChildProcess;
-    try {
-      child = s.spawn(resolveBin(kind, s), ["login"]);
-    } catch (err) {
-      done({ ok: false, message: err instanceof Error ? err.message : String(err) });
-      return;
-    }
     child.stdout?.on("data", (b: Buffer) => relay(b.toString("utf8"), onLog));
     child.stderr?.on("data", (b: Buffer) => relay(b.toString("utf8"), onLog));
     child.on("error", (err: NodeJS.ErrnoException) =>

package/lib/standard-image.ts

@@ -18,12 +18,12 @@
 
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { detectEngine } from "./engines";
+
 /** Pinned, host-wide constants (must match task-up.sh and the compose gen). */
 export const STANDARD_IMAGE_TAG = "uai-standard:dev";
 export const ASDF_DATA_VOLUME = "uai-asdf-data";
@@ -71,23 +71,21 @@ const CONTEXT_HASH_LABEL = "com.runuai.context-hash";
  */
 /**
  * Which OPTIONAL agent CLIs the operator has actually configured — so the
- * image installs only those, not every engine on every host. Keyed on the
- * same credential each adapter's `available()` checks (kimi/grok are copied
- * into containers at task-up; claude/codex are always baked). Folded into the
- * build hash below, so logging into a new engine triggers a rebuild.
+ * image installs only those, not every engine on every host. Delegates to
+ * engines.ts detection so every connect flavor counts: kimi's copied cred
+ * file, grok's login file OR a pasted XAI_API_KEY, cursor's CURSOR_API_KEY
+ * (claude/codex are always baked). Folded into the build hash below, so
+ * connecting a new engine triggers a rebuild.
  */
 export function configuredOptionalEngines(): {
   kimi: boolean;
   grok: boolean;
   cursor: boolean;
 } {
-  const home = process.env.UAI_OWNER_HOME?.trim() || homedir();
   return {
-    kimi: existsSync(join(home, ".kimi-code", "credentials", "kimi-code.json")),
-    grok: existsSync(join(home, ".grok", "auth.json")),
-    // Cursor auths via CURSOR_API_KEY (env, loaded from .env.local), not a
-    // config file — install it when the key is present.
-    cursor: Boolean(process.env.CURSOR_API_KEY),
+    kimi: detectEngine("kimi"),
+    grok: detectEngine("grok"),
+    cursor: detectEngine("cursor"),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.8.9",
+  "version": "0.8.11",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

package/scripts/agent/task-up.sh

@@ -365,6 +365,11 @@ fi
   # claude and the code-server terminal's interactive claude authenticate.
   printf '      %s: "${%s:-}"\n' \
     "CLAUDE_CODE_OAUTH_TOKEN" "CLAUDE_CODE_OAUTH_TOKEN"
+  # Pasted engine API keys (ADR-070) ride the same at-up interpolation, so the
+  # terminal CLIs authenticate like the adapters' exec-time env forwarding.
+  printf '      %s: "${%s:-}"\n' "ANTHROPIC_API_KEY" "ANTHROPIC_API_KEY"
+  printf '      %s: "${%s:-}"\n' "ANTHROPIC_AUTH_TOKEN" "ANTHROPIC_AUTH_TOKEN"
+  printf '      %s: "${%s:-}"\n' "XAI_API_KEY" "XAI_API_KEY"
   # ADR-053: point Playwright at the shared browser cache volume.
   printf '      PLAYWRIGHT_BROWSERS_PATH: "/opt/pw-browsers"\n'
   # No GH_TOKEN/GITHUB_TOKEN in the container env (ADR-027). `gh` prefers such

package/src/ui/types.ts

@@ -81,6 +81,9 @@ export const EngineCatalogEntry = z.object({
   authMode: z.enum(["token-command", "login-command", "api-key"]),
   notes: z.string().nullable(),
   getKeyUrl: z.string().nullable(),
+  // Pasted-API-key alternative to the login/token flow (null = not offered).
+  apiKeyHint: z.string().nullable(),
+  apiKeyUrl: z.string().nullable(),
 });
 export type EngineCatalogEntry = z.infer<typeof EngineCatalogEntry>;
 

package/ui/app.js

@@ -516,19 +516,25 @@ function commandForm(e) {
   actions.append(connect);
   form.append(actions, status, log);
 
-  // Claude: a manual paste fallback for when the browser flow isn't possible.
-  if (e.authMode === "token-command") {
+  // Manual paste fallback for when the browser flow isn't possible: Claude
+  // takes a token or API key (one box, classified server-side); login-command
+  // engines with an apiKeyHint (Codex, Grok) take an API key.
+  const isToken = e.authMode === "token-command";
+  if (isToken || e.apiKeyHint) {
+    const saveLabel = isToken ? "Save token" : "Save key";
     const pasteToggle = document.createElement("button");
     pasteToggle.className = "link-btn";
     pasteToggle.type = "button";
-    pasteToggle.textContent = "Paste a token instead";
+    pasteToggle.textContent = isToken
+      ? "Paste a token or API key instead"
+      : "Use an API key instead";
     const pasteWrap = document.createElement("div");
     pasteWrap.className = "engine-setup";
     pasteWrap.hidden = true;
     const pInput = document.createElement("input");
     pInput.type = "password";
     pInput.className = "text-input";
-    pInput.placeholder = "sk-ant-oat…";
+    pInput.placeholder = e.apiKeyHint || "sk-ant-…";
     pInput.autocomplete = "off";
     pInput.spellcheck = false;
     const pField = document.createElement("div");
@@ -539,30 +545,42 @@ function commandForm(e) {
     const pSave = document.createElement("button");
     pSave.className = "btn";
     pSave.type = "button";
-    pSave.textContent = "Save token";
+    pSave.textContent = saveLabel;
     pSave.addEventListener("click", async () => {
-      const pastedToken = pInput.value.trim();
-      if (!pastedToken) {
+      const value = pInput.value.trim();
+      if (!value) {
         pStatus.className = "setup-status err";
-        pStatus.textContent = "Paste a token first.";
+        pStatus.textContent = isToken ? "Paste a token first." : "Paste a key first.";
         return;
       }
       pSave.disabled = true;
       pSave.textContent = "Saving…";
-      const result = await runConnect({ kind: e.kind, pastedToken });
+      const body = isToken
+        ? { kind: e.kind, pastedToken: value }
+        : { kind: e.kind, apiKey: value };
+      const result = await runConnect(body);
       if (result.ok) {
         await poll();
         closeModal();
       } else {
         pSave.disabled = false;
-        pSave.textContent = "Save token";
+        pSave.textContent = saveLabel;
         pStatus.className = "setup-status err";
-        pStatus.textContent = result.message || "Couldn't save the token.";
+        pStatus.textContent = result.message || "Couldn't save it.";
       }
     });
     const pActions = document.createElement("div");
     pActions.className = "setup-actions";
     pActions.append(pSave);
+    if (e.apiKeyUrl) {
+      const link = document.createElement("a");
+      link.className = "link-btn";
+      link.href = e.apiKeyUrl;
+      link.target = "_blank";
+      link.rel = "noreferrer";
+      link.textContent = "Get a key";
+      pActions.append(link);
+    }
     pasteWrap.append(pField, pActions, pStatus);
     pasteToggle.addEventListener("click", () => {
       pasteWrap.hidden = !pasteWrap.hidden;