fix(config): accept the Intelligence runtime key written by the CLI

Author: samjulien

.env.example

@@ -129,12 +129,13 @@ INTELLIGENCE_GATEWAY_WS_URL=wss://realtime.intelligence.copilotkit.ai
 #
 #   npx --yes copilotkit@latest login           # browser sign-in
 #   npx --yes copilotkit@latest project select  # writes the cpk-... key to .env as CPK_INTELLIGENCE_API_KEY
-#   bun scripts/setup-learning.ts               # copies it here, as INTELLIGENCE_API_KEY
+#   bun scripts/setup-learning.ts             # ensures the Learning container exists
 #
-# The server reads only INTELLIGENCE_API_KEY, so a key left as CPK_INTELLIGENCE_API_KEY is not seen.
+# OpenBot reads CPK_INTELLIGENCE_API_KEY directly. INTELLIGENCE_API_KEY is a legacy fallback.
+# When both are set, the non-empty CPK_INTELLIGENCE_API_KEY takes precedence.
 #
 # The runtime key is also under "API Keys" in your project at https://intelligence.copilotkit.ai
-INTELLIGENCE_API_KEY=
+CPK_INTELLIGENCE_API_KEY=
 
 # Optional, and blank on purpose. Managed Intelligence derives entitlement from the project key
 # above and issues no licence token. A self-hosted Intelligence with its own licence sets this and

README.md

@@ -138,13 +138,10 @@ not a production installation. Run its
 `npx copilotkit@latest local connect` from the OpenBot root, where `.env` is.
 
 That command writes `INTELLIGENCE_API_URL`, `INTELLIGENCE_GATEWAY_WS_URL` and
-`CPK_INTELLIGENCE_API_KEY` to `.env`. OpenBot reads the first two as they are, but takes its project
-key only from `INTELLIGENCE_API_KEY` and refuses to start without it, so copy the `cpk-...` value
-across before `bash scripts/start.sh`:
-
-```sh
-INTELLIGENCE_API_KEY=cpk-...   # the value of CPK_INTELLIGENCE_API_KEY
-```
+`CPK_INTELLIGENCE_API_KEY` to `.env`. OpenBot reads those settings directly; no key
+copying or renaming is needed. `INTELLIGENCE_API_KEY` remains supported for older
+configurations. When both are set, the non-empty CLI key takes precedence so
+reconnecting uses the new project's key.
 
 To give the Bots a Learning container on that stack, see
 [Automatic Learning](docs/automatic-learning.md).

docs/configuration.md

@@ -22,7 +22,8 @@ bash scripts/start.sh
 | `KEY_ENCRYPTION_KEY`          | Base64-encoded 32-byte key for encrypted stored credentials. Generate with `openssl rand -base64 32`. |
 | `INTELLIGENCE_API_URL`        | CopilotKit Intelligence API URL.                                                                      |
 | `INTELLIGENCE_GATEWAY_WS_URL` | CopilotKit Intelligence realtime gateway URL.                                                         |
-| `INTELLIGENCE_API_KEY`        | Runtime key for the Intelligence project.                                                             |
+| `CPK_INTELLIGENCE_API_KEY` | Runtime key written by the CopilotKit CLI. Preferred when non-empty. |
+| `INTELLIGENCE_API_KEY` | Legacy runtime key; used when `CPK_INTELLIGENCE_API_KEY` is empty or absent. |
 
 All five above stop server startup if missing. The three `INTELLIGENCE_` values are additionally
 checked as a set, so a partial set is refused as a misconfiguration rather than treated as

prompt.txt

@@ -103,9 +103,9 @@ OpenBot root where `.env` is:
   npx copilotkit@latest local connect --approve-connection
 
 `local connect` writes INTELLIGENCE_API_URL, INTELLIGENCE_GATEWAY_WS_URL and
-CPK_INTELLIGENCE_API_KEY to `.env`. OpenBot reads the first two as they are but takes its project
-key only from INTELLIGENCE_API_KEY, so copy the `cpk-...` value of CPK_INTELLIGENCE_API_KEY into
-INTELLIGENCE_API_KEY before `bash scripts/start.sh`. The local licence lasts 30 days;
+CPK_INTELLIGENCE_API_KEY to `.env`. OpenBot reads those values directly; do not copy or rename
+the key. INTELLIGENCE_API_KEY remains a legacy fallback when the CLI key is empty or absent.
+When both are set, the non-empty CLI key takes precedence. The local licence lasts 30 days;
 `npx copilotkit@latest local renew` renews it as often as needed while the account is in good
 standing. Skip the managed `project select` and setup-learning commands on this path.
 

scripts/setup-learning.test.ts

@@ -601,8 +601,27 @@ test("self-hosted setup failure or concurrent env edits do not save credentials"
   );
 });
 
-test("a partial key provision cannot reuse a stale CLI key or create a container", async () => {
-  const f = await fixture("CPK_INTELLIGENCE_API_KEY=cpk-old-project-key\n");
+test.each(["", "INTELLIGENCE_API_KEY=cpk-old-project-key\n"])(
+  "a CLI key is used without reprovisioning or rewriting configuration: %s",
+  async (legacy) => {
+    const f = await fixture(`${legacy}CPK_INTELLIGENCE_API_KEY=cpk-cli-key\n`);
+    const before = await readFile(f.envPath, "utf8");
+    const view = keyView(["present"]);
+    expect(
+      await setupLearning({
+        ...f.options,
+        runCli: f.runCli,
+        keyIntelligence: view.keyIntelligence,
+      }),
+    ).toBe("present");
+    expect(view.keys).toEqual(["cpk-cli-key"]);
+    expect(f.calls).toHaveLength(0);
+    expect(await readFile(f.envPath, "utf8")).toBe(before);
+  },
+);
+
+test("a partial key provision does not create a container", async () => {
+  const f = await fixture();
   const before = await readFile(f.envPath, "utf8");
   await expect(
     setupLearning({

scripts/setup-learning.ts

@@ -2,6 +2,7 @@ import { readFile, rename, rm, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { parseEnv } from "node:util";
+import { intelligenceApiKey } from "../shared/intelligence-key";
 import {
   cliLoginPresent,
   containerMissing,
@@ -136,7 +137,10 @@ export async function setupLearning(
   const effective = (name: string) =>
     (environment[name] || values[name] || "").trim();
   if (effective(CONTAINER)) return "preserved";
-  const existingKey = effective("INTELLIGENCE_API_KEY");
+  const existingKey = intelligenceApiKey({
+    CPK_INTELLIGENCE_API_KEY: effective("CPK_INTELLIGENCE_API_KEY"),
+    INTELLIGENCE_API_KEY: effective("INTELLIGENCE_API_KEY"),
+  });
   if (existingKey) {
     /*
      * The key cannot create containers, and it is never replaced here. Creation goes through a

scripts/start-restart-guard.test.ts

@@ -351,17 +351,20 @@ describe("start.sh Learning container check", () => {
    * The server assigns `openbot` once it exists, but its runtime key cannot create it. start.sh asks
    * the setup helper, without a browser or a prompt, to make sure it exists, and relays its last line.
    */
-  test("runs the non-interactive check when a key is set and nothing is assigned", async () => {
-    const result = await runStartWithStaleServerProbe(401, {
-      settings: { INTELLIGENCE_API_KEY: "cpk-synthetic" },
-    });
+  test.each(["INTELLIGENCE_API_KEY", "CPK_INTELLIGENCE_API_KEY"])(
+    "runs the non-interactive check when %s is set",
+    async (keyName) => {
+      const result = await runStartWithStaleServerProbe(401, {
+        settings: { [keyName]: "cpk-synthetic" },
+      });
 
-    expect(result.exitCode).toBe(0);
-    expect(result.stdout).toContain(
-      "LEARNING-CHECK scripts/setup-learning.ts --non-interactive",
-    );
-    expect(result.stdout).not.toContain("noise");
-  });
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain(
+        "LEARNING-CHECK scripts/setup-learning.ts --non-interactive",
+      );
+      expect(result.stdout).not.toContain("noise");
+    },
+  );
 
   test.each([
     [

scripts/start.sh

@@ -300,7 +300,7 @@ green "  managed coworker endpoint: $MANAGED_AGENT_AG_UI_URL"
 LEARNING_CONTAINER="$(setting CPK_INTELLIGENCE_LEARNING_CONTAINER_ID "")"
 LEARNING_AUTO_ASSIGN="$(setting OPENBOT_LEARNING_AUTO_ASSIGN true)"
 if [ -z "$LEARNING_CONTAINER" ] && [ "$LEARNING_AUTO_ASSIGN" != "false" ] \
-   && [ "$LEARNING_AUTO_ASSIGN" != "0" ] && [ -n "$(setting INTELLIGENCE_API_KEY "")" ]; then
+   && [ "$LEARNING_AUTO_ASSIGN" != "0" ] && { [ -n "$(setting CPK_INTELLIGENCE_API_KEY "")" ] || [ -n "$(setting INTELLIGENCE_API_KEY "")" ]; }; then
   LEARNING_LINE="$(bun scripts/setup-learning.ts --non-interactive 2>>"$LOGS/learning-setup.log" | tail -1 || true)"
   info "  ${LEARNING_LINE:-Automatic Learning: the container check did not run. Log: $LOGS/learning-setup.log}"
 fi
@@ -413,7 +413,7 @@ const status = info.licenseStatus;
 const agents = Object.keys(info.agents ?? {});
 if (status !== "valid") {
   console.log(`\x1b[31m  licence is '${status}', not 'valid'.\x1b[0m`);
-  console.log("\x1b[31m  Check INTELLIGENCE_API_KEY: npx copilotkit@latest login && npx copilotkit@latest project select\x1b[0m");
+  console.log("\x1b[31m  Check CPK_INTELLIGENCE_API_KEY (or INTELLIGENCE_API_KEY): npx copilotkit@latest login && npx copilotkit@latest project select\x1b[0m");
   console.log("\x1b[31m  See README.md for Intelligence setup.\x1b[0m");
   process.exit(1);
 }

server/src/config.ts

@@ -3,6 +3,7 @@
  * for durable threads and memory. Configuration the product cannot function without belongs at the
  * boot boundary.
  */
+import { intelligenceApiKey } from "@openbot/shared/intelligence-key";
 import {
   isLearningContainerId,
   type LearningTarget,
@@ -950,7 +951,7 @@ function runtimeCapabilities(environment: Environment): RuntimeCapabilities {
   const settings = {
     apiUrl: url(environment, "INTELLIGENCE_API_URL"),
     gatewayWsUrl: url(environment, "INTELLIGENCE_GATEWAY_WS_URL"),
-    apiKey: optional(environment, "INTELLIGENCE_API_KEY"),
+    apiKey: intelligenceApiKey(environment),
     licenseToken: optional(environment, "COPILOTKIT_LICENSE_TOKEN"),
   };
 

server/src/learning/ensure-container.ts

@@ -21,6 +21,7 @@
  * Shared by `scripts/setup-learning.ts` (run by `scripts/start.sh`), the server (at boot and from
  * Admin → Automatic Learning), and the Helm chart's setup Job, which runs this file directly.
  */
+import { intelligenceApiKey } from "@openbot/shared/intelligence-key";
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
@@ -536,8 +537,11 @@ export async function ensureLearningContainer(input: {
 async function jobMain() {
   const environment = process.env;
   const apiUrl = intelligenceApiOrigin(environment.INTELLIGENCE_API_URL ?? "");
-  const apiKey = environment.INTELLIGENCE_API_KEY?.trim();
-  if (!apiKey) throw new Error("INTELLIGENCE_API_KEY is required.");
+  const apiKey = intelligenceApiKey(environment);
+  if (!apiKey)
+    throw new Error(
+      "CPK_INTELLIGENCE_API_KEY (or INTELLIGENCE_API_KEY) is required.",
+    );
   const token = environment.INTELLIGENCE_SERVICE_TOKEN?.trim();
   const projectId = environment.INTELLIGENCE_PROJECT_ID?.trim();
   if (Boolean(token) !== Boolean(projectId))