@vellumai/cli 0.5.4 → 0.5.5

package/AGENTS.md

@@ -40,3 +40,15 @@ Every command must have high-quality `--help` output. Follow the same standards
 3. **Write for machines**: Be precise about formats, constraints, and side effects.
    AI agents parse help text to decide which command to run and how. Avoid vague
    language — say exactly what the command does and where state is stored.
+
+## Docker Volume Management
+
+The CLI creates and manages Docker volumes for containerized instances. See the root `AGENTS.md` § Docker Volume Architecture for the full volume layout.
+
+**Volume creation** (`hatch`): Creates four volumes per instance — workspace, gateway-security, ces-security, and socket. The legacy data volume is no longer created.
+
+**Volume migration** (`wake`/`hatch`): On startup, existing instances that still have a legacy data volume are migrated. `migrateGatewaySecurityFiles()` and `migrateCesSecurityFiles()` in `lib/docker.ts` copy security files from the data volume to their respective security volumes. Migrations are idempotent and non-fatal.
+
+**Volume cleanup** (`retire`): All volumes (including the legacy data volume if it exists) are removed when an instance is retired.
+
+**Volume mount rules**: Each service container receives only the volumes it needs. The assistant never mounts `gateway-security` or `ces-security`. The gateway never mounts `ces-security`. The CES mounts the workspace volume as read-only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/assistant-config.test.ts

@@ -238,6 +238,7 @@ describe("migrateLegacyEntry", () => {
     expect(resources.daemonPort).toBe(7821);
     expect(resources.gatewayPort).toBe(7830);
     expect(resources.qdrantPort).toBe(6333);
+    expect(resources.cesPort).toBe(8090);
     expect(resources.pidFile).toContain("vellum.pid");
   });
 
@@ -310,6 +311,7 @@ describe("migrateLegacyEntry", () => {
     expect(resources.daemonPort).toBe(7821);
     expect(resources.gatewayPort).toBe(7830);
     expect(resources.qdrantPort).toBe(6333);
+    expect(resources.cesPort).toBe(8090);
     expect(resources.pidFile).toBe("/custom/path/.vellum/vellum.pid");
   });
 
@@ -328,6 +330,7 @@ describe("migrateLegacyEntry", () => {
         daemonPort: 8000,
         gatewayPort: 8001,
         qdrantPort: 8002,
+        cesPort: 8003,
         pidFile: "/my/path/.vellum/vellum.pid",
       },
     };
@@ -343,6 +346,7 @@ describe("migrateLegacyEntry", () => {
     expect(resources.daemonPort).toBe(8000);
     expect(resources.gatewayPort).toBe(8001);
     expect(resources.qdrantPort).toBe(8002);
+    expect(resources.cesPort).toBe(8003);
   });
 
   test("baseDataDir does not overwrite existing resources.instanceDir", () => {
@@ -377,6 +381,48 @@ describe("migrateLegacyEntry", () => {
     const resources = entry.resources as Record<string, unknown>;
     expect(resources.instanceDir).toBe("/new/path");
   });
+
+  test("backfills cesPort with default 8090", () => {
+    // GIVEN a local entry with resources that has no cesPort
+    const entry: Record<string, unknown> = {
+      assistantId: "no-ces-port",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+      resources: {
+        instanceDir: "/custom/path",
+        daemonPort: 7821,
+        gatewayPort: 7830,
+        qdrantPort: 6333,
+        pidFile: "/custom/path/.vellum/vellum.pid",
+      },
+    };
+    // WHEN we migrate the entry
+    const changed = migrateLegacyEntry(entry);
+    // THEN cesPort should be backfilled
+    expect(changed).toBe(true);
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.cesPort).toBe(8090);
+  });
+
+  test("does not overwrite existing cesPort", () => {
+    const entry: Record<string, unknown> = {
+      assistantId: "has-ces-port",
+      runtimeUrl: "http://localhost:7830",
+      cloud: "local",
+      resources: {
+        instanceDir: "/my/path",
+        daemonPort: 8000,
+        gatewayPort: 8001,
+        qdrantPort: 8002,
+        cesPort: 9090,
+        pidFile: "/my/path/.vellum/vellum.pid",
+      },
+    };
+    const changed = migrateLegacyEntry(entry);
+    expect(changed).toBe(false);
+    const resources = entry.resources as Record<string, unknown>;
+    expect(resources.cesPort).toBe(9090);
+  });
 });
 
 describe("legacy migration via loadAllAssistants", () => {

package/src/adapters/openclaw.ts

@@ -3,7 +3,7 @@ import { buildOpenclawRuntimeServer } from "../lib/openclaw-runtime-server";
 
 export async function buildOpenclawStartupScript(
   sshUser: string,
-  anthropicApiKey: string,
+  providerApiKeys: Record<string, string>,
   timestampRedirect: string,
   userSetup: string,
   ownershipFixup: string,
@@ -110,7 +110,9 @@ echo -n "\$OPENCLAW_GW_TOKEN" > /tmp/openclaw-gateway-token
 chmod 600 /tmp/openclaw-gateway-token
 
 mkdir -p /root/.openclaw
-openclaw config set env.ANTHROPIC_API_KEY "${anthropicApiKey}"
+${Object.entries(providerApiKeys)
+  .map(([envVar, value]) => `openclaw config set env.${envVar} "${value}"`)
+  .join("\n")}
 openclaw config set agents.defaults.model.primary "anthropic/claude-opus-4-6"
 openclaw config set gateway.auth.token "\$OPENCLAW_GW_TOKEN"
 

package/src/commands/backup.ts

@@ -0,0 +1,151 @@
+import { mkdirSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+import { findAssistantByName } from "../lib/assistant-config";
+import { loadGuardianToken, leaseGuardianToken } from "../lib/guardian-token";
+
+function getBackupsDir(): string {
+  const dataHome =
+    process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share");
+  return join(dataHome, "vellum", "backups");
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export async function backup(): Promise<void> {
+  const args = process.argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log("Usage: vellum backup <name> [--output <path>]");
+    console.log("");
+    console.log(
+      "Export a backup of a running assistant as a .vbundle archive.",
+    );
+    console.log("");
+    console.log("Arguments:");
+    console.log("  <name>              Name of the assistant to back up");
+    console.log("");
+    console.log("Options:");
+    console.log("  --output <path>     Path to save the .vbundle file");
+    console.log(
+      "                      (default: ~/.local/share/vellum/backups/<name>-<timestamp>.vbundle)",
+    );
+    console.log("");
+    console.log("Examples:");
+    console.log("  vellum backup my-assistant");
+    console.log(
+      "  vellum backup my-assistant --output ~/Desktop/backup.vbundle",
+    );
+    process.exit(0);
+  }
+
+  const name = args[0];
+  if (!name || name.startsWith("-")) {
+    console.error("Usage: vellum backup <name> [--output <path>]");
+    process.exit(1);
+  }
+
+  // Parse --output flag
+  let outputArg: string | undefined;
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--output" && args[i + 1]) {
+      outputArg = args[i + 1];
+      break;
+    }
+  }
+
+  // Look up the instance
+  const entry = findAssistantByName(name);
+  if (!entry) {
+    console.error(`No assistant found with name '${name}'.`);
+    console.error("Run 'vellum hatch' first, or check the instance name.");
+    process.exit(1);
+  }
+
+  // Obtain an auth token
+  let accessToken: string;
+  const tokenData = loadGuardianToken(entry.assistantId);
+  if (tokenData && new Date(tokenData.accessTokenExpiresAt) > new Date()) {
+    accessToken = tokenData.accessToken;
+  } else {
+    try {
+      const freshToken = await leaseGuardianToken(
+        entry.runtimeUrl,
+        entry.assistantId,
+      );
+      accessToken = freshToken.accessToken;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+        console.error(
+          `Error: Could not connect to assistant '${name}'. Is it running?`,
+        );
+        console.error(`Try: vellum wake ${name}`);
+        process.exit(1);
+      }
+      throw err;
+    }
+  }
+
+  // Call the export endpoint
+  let response: Response;
+  try {
+    response = await fetch(`${entry.runtimeUrl}/v1/migrations/export`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ description: "CLI backup" }),
+      signal: AbortSignal.timeout(120_000),
+    });
+  } catch (err) {
+    if (err instanceof Error && err.name === "TimeoutError") {
+      console.error("Error: Export request timed out after 2 minutes.");
+      process.exit(1);
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+      console.error(
+        `Error: Could not connect to assistant '${name}'. Is it running?`,
+      );
+      console.error(`Try: vellum wake ${name}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  if (!response.ok) {
+    const body = await response.text();
+    console.error(`Error: Export failed (${response.status}): ${body}`);
+    process.exit(1);
+  }
+
+  // Read the response body
+  const arrayBuffer = await response.arrayBuffer();
+  const data = new Uint8Array(arrayBuffer);
+
+  // Determine output path
+  const isoTimestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const outputPath =
+    outputArg || join(getBackupsDir(), `${name}-${isoTimestamp}.vbundle`);
+
+  // Ensure parent directory exists
+  mkdirSync(dirname(outputPath), { recursive: true });
+
+  // Write the archive to disk
+  writeFileSync(outputPath, data);
+
+  // Print success
+  const manifestSha = response.headers.get("X-Vbundle-Manifest-Sha256");
+  console.log(`Backup saved to ${outputPath}`);
+  console.log(`Size: ${formatSize(data.byteLength)}`);
+  if (manifestSha) {
+    console.log(`Manifest SHA-256: ${manifestSha}`);
+  }
+}

package/src/commands/hatch.ts

@@ -96,7 +96,7 @@ chown -R "$SSH_USER:$SSH_USER" "$SSH_USER_HOME" 2>/dev/null || true
 export async function buildStartupScript(
   species: Species,
   sshUser: string,
-  anthropicApiKey: string,
+  providerApiKeys: Record<string, string>,
   instanceName: string,
   cloud: RemoteHost,
 ): Promise<string> {
@@ -114,13 +114,22 @@ export async function buildStartupScript(
   if (species === "openclaw") {
     return await buildOpenclawStartupScript(
       sshUser,
-      anthropicApiKey,
+      providerApiKeys,
       timestampRedirect,
       userSetup,
       ownershipFixup,
     );
   }
 
+  // Build bash lines that set each provider API key as a shell variable
+  // and corresponding dotenv lines for the env file.
+  const envSetLines = Object.entries(providerApiKeys)
+    .map(([envVar, value]) => `${envVar}=${value}`)
+    .join("\n");
+  const dotenvLines = Object.keys(providerApiKeys)
+    .map((envVar) => `${envVar}=\$${envVar}`)
+    .join("\n");
+
   return `#!/bin/bash
 set -e
 
@@ -128,11 +137,11 @@ ${timestampRedirect}
 
 trap 'EXIT_CODE=\$?; if [ \$EXIT_CODE -ne 0 ]; then echo "Startup script failed with exit code \$EXIT_CODE at line \$LINENO" > ${errorPath}; echo "Last 20 log lines:" >> ${errorPath}; tail -20 ${logPath} >> ${errorPath} 2>/dev/null || true; fi' EXIT
 ${userSetup}
-ANTHROPIC_API_KEY=${anthropicApiKey}
+${envSetLines}
 VELLUM_ASSISTANT_NAME=${instanceName}
 mkdir -p "\$HOME/.config/vellum"
 cat > "\$HOME/.config/vellum/env" << DOTENV_EOF
-ANTHROPIC_API_KEY=\$ANTHROPIC_API_KEY
+${dotenvLines}
 RUNTIME_HTTP_PORT=7821
 DOTENV_EOF
 
@@ -749,6 +758,7 @@ async function hatchLocal(
     cloud: "local",
     species,
     hatchedAt: new Date().toISOString(),
+    serviceGroupVersion: cliPkg.version ? `v${cliPkg.version}` : undefined,
     resources,
   };
   if (!daemonOnly && !restart) {

package/src/commands/restore.ts

@@ -0,0 +1,310 @@
+import { existsSync, readFileSync } from "fs";
+
+import { findAssistantByName } from "../lib/assistant-config.js";
+import {
+  loadGuardianToken,
+  leaseGuardianToken,
+} from "../lib/guardian-token.js";
+
+function printUsage(): void {
+  console.log("Usage: vellum restore <name> --from <path> [--dry-run]");
+  console.log("");
+  console.log("Restore a .vbundle backup into a running assistant.");
+  console.log("");
+  console.log("Arguments:");
+  console.log("  <name>              Name of the assistant to restore into");
+  console.log("");
+  console.log("Options:");
+  console.log(
+    "  --from <path>       Path to the .vbundle file to restore (required)",
+  );
+  console.log("  --dry-run           Show what would change without applying");
+  console.log("");
+  console.log("Examples:");
+  console.log("  vellum restore my-assistant --from ~/Desktop/backup.vbundle");
+  console.log(
+    "  vellum restore my-assistant --from ~/Desktop/backup.vbundle --dry-run",
+  );
+}
+
+function parseArgs(argv: string[]): {
+  name: string | undefined;
+  fromPath: string | undefined;
+  dryRun: boolean;
+  help: boolean;
+} {
+  const args = argv.slice(3);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    return { name: undefined, fromPath: undefined, dryRun: false, help: true };
+  }
+
+  let fromPath: string | undefined;
+  const dryRun = args.includes("--dry-run");
+  const positionals: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--from" && args[i + 1]) {
+      fromPath = args[i + 1];
+      i++; // skip the value
+    } else if (args[i] === "--dry-run") {
+      // already handled above
+    } else if (!args[i].startsWith("-")) {
+      positionals.push(args[i]);
+    }
+  }
+
+  return { name: positionals[0], fromPath, dryRun, help: false };
+}
+
+async function getAccessToken(
+  runtimeUrl: string,
+  assistantId: string,
+  displayName: string,
+): Promise<string> {
+  const tokenData = loadGuardianToken(assistantId);
+
+  if (tokenData && new Date(tokenData.accessTokenExpiresAt) > new Date()) {
+    return tokenData.accessToken;
+  }
+
+  try {
+    const freshToken = await leaseGuardianToken(runtimeUrl, assistantId);
+    return freshToken.accessToken;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+      console.error(
+        `Error: Could not connect to assistant '${displayName}'. Is it running?`,
+      );
+      console.error(`Try: vellum wake ${displayName}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+interface PreflightFileEntry {
+  path: string;
+  action: string;
+}
+
+interface PreflightResponse {
+  can_import: boolean;
+  errors?: string[];
+  files?: PreflightFileEntry[];
+  summary?: {
+    create: number;
+    overwrite: number;
+    unchanged: number;
+    total: number;
+  };
+  conflicts?: string[];
+}
+
+interface ImportResponse {
+  success: boolean;
+  reason?: string;
+  errors?: string[];
+  warnings?: string[];
+  summary?: {
+    created: number;
+    overwritten: number;
+    skipped: number;
+    backups_created: number;
+  };
+}
+
+export async function restore(): Promise<void> {
+  const { name, fromPath, dryRun, help } = parseArgs(process.argv);
+
+  if (help) {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (!name || !fromPath) {
+    console.error("Error: Both <name> and --from <path> are required.");
+    console.error("");
+    printUsage();
+    process.exit(1);
+  }
+
+  // Look up the instance
+  const entry = findAssistantByName(name);
+  if (!entry) {
+    console.error(`Error: No assistant found with name '${name}'.`);
+    console.error("Run 'vellum ps' to see available assistants.");
+    process.exit(1);
+  }
+
+  // Verify .vbundle file exists
+  if (!existsSync(fromPath)) {
+    console.error(`Error: File not found: ${fromPath}`);
+    process.exit(1);
+  }
+
+  // Read the .vbundle file
+  const bundleData = readFileSync(fromPath);
+  const sizeMB = (bundleData.byteLength / (1024 * 1024)).toFixed(2);
+  console.log(`Reading ${fromPath} (${sizeMB} MB)...`);
+
+  // Obtain auth token
+  const accessToken = await getAccessToken(
+    entry.runtimeUrl,
+    entry.assistantId,
+    name,
+  );
+
+  if (dryRun) {
+    // Preflight check
+    console.log("Running preflight analysis...\n");
+
+    let response: Response;
+    try {
+      response = await fetch(
+        `${entry.runtimeUrl}/v1/migrations/import-preflight`,
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/octet-stream",
+          },
+          body: bundleData,
+          signal: AbortSignal.timeout(120_000),
+        },
+      );
+    } catch (err) {
+      if (err instanceof Error && err.name === "TimeoutError") {
+        console.error("Error: Preflight request timed out after 2 minutes.");
+        process.exit(1);
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+        console.error(
+          `Error: Could not connect to assistant '${name}'. Is it running?`,
+        );
+        console.error(`Try: vellum wake ${name}`);
+        process.exit(1);
+      }
+      throw err;
+    }
+
+    if (!response.ok) {
+      const body = await response.text();
+      console.error(
+        `Error: Preflight check failed (${response.status}): ${body}`,
+      );
+      process.exit(1);
+    }
+
+    const result = (await response.json()) as PreflightResponse;
+
+    if (!result.can_import) {
+      console.error("Import blocked by validation errors:");
+      for (const err of result.errors ?? []) {
+        console.error(`  - ${err}`);
+      }
+      process.exit(1);
+    }
+
+    // Print summary table
+    const summary = result.summary ?? {
+      create: 0,
+      overwrite: 0,
+      unchanged: 0,
+      total: 0,
+    };
+    console.log("Preflight analysis:");
+    console.log(`  Files to create:    ${summary.create}`);
+    console.log(`  Files to overwrite: ${summary.overwrite}`);
+    console.log(`  Files unchanged:    ${summary.unchanged}`);
+    console.log(`  Total:              ${summary.total}`);
+    console.log("");
+
+    const conflicts = result.conflicts ?? [];
+    console.log(
+      `Conflicts: ${conflicts.length > 0 ? conflicts.join(", ") : "none"}`,
+    );
+
+    // List individual files with their action
+    if (result.files && result.files.length > 0) {
+      console.log("");
+      console.log("Files:");
+      for (const file of result.files) {
+        console.log(`  [${file.action}] ${file.path}`);
+      }
+    }
+  } else {
+    // Full import
+    console.log("Importing backup...\n");
+
+    let response: Response;
+    try {
+      response = await fetch(`${entry.runtimeUrl}/v1/migrations/import`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/octet-stream",
+        },
+        body: bundleData,
+        signal: AbortSignal.timeout(120_000),
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === "TimeoutError") {
+        console.error("Error: Import request timed out after 2 minutes.");
+        process.exit(1);
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+        console.error(
+          `Error: Could not connect to assistant '${name}'. Is it running?`,
+        );
+        console.error(`Try: vellum wake ${name}`);
+        process.exit(1);
+      }
+      throw err;
+    }
+
+    if (!response.ok) {
+      const body = await response.text();
+      console.error(`Error: Import failed (${response.status}): ${body}`);
+      process.exit(1);
+    }
+
+    const result = (await response.json()) as ImportResponse;
+
+    if (!result.success) {
+      console.error(
+        `Error: Import failed — ${result.reason ?? "unknown reason"}`,
+      );
+      for (const err of result.errors ?? []) {
+        console.error(`  - ${err}`);
+      }
+      process.exit(1);
+    }
+
+    // Print import report
+    const summary = result.summary ?? {
+      created: 0,
+      overwritten: 0,
+      skipped: 0,
+      backups_created: 0,
+    };
+    console.log("✅ Restore complete.");
+    console.log(`  Files created:     ${summary.created}`);
+    console.log(`  Files overwritten: ${summary.overwritten}`);
+    console.log(`  Files skipped:     ${summary.skipped}`);
+    console.log(`  Backups created:   ${summary.backups_created}`);
+
+    // Print warnings if any
+    const warnings = result.warnings ?? [];
+    if (warnings.length > 0) {
+      console.log("");
+      console.log("Warnings:");
+      for (const warning of warnings) {
+        console.log(`  ⚠️  ${warning}`);
+      }
+    }
+  }
+}

package/src/commands/upgrade.ts

@@ -1,9 +1,12 @@
+import { randomBytes } from "crypto";
+
 import cliPkg from "../../package.json";
 
 import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
+  saveAssistantEntry,
 } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
 import {
@@ -12,6 +15,8 @@ import {
   DOCKER_READY_TIMEOUT_MS,
   GATEWAY_INTERNAL_PORT,
   dockerResourceNames,
+  migrateCesSecurityFiles,
+  migrateGatewaySecurityFiles,
   startContainers,
   stopContainers,
 } from "../lib/docker";
@@ -257,10 +262,18 @@ async function upgradeDocker(
     // use default
   }
 
+  // Extract CES_SERVICE_TOKEN from the captured env so it can be passed via
+  // the dedicated cesServiceToken parameter (which propagates it to all three
+  // containers). If the old instance predates CES_SERVICE_TOKEN, generate a
+  // fresh one so gateway and CES can authenticate.
+  const cesServiceToken =
+    capturedEnv["CES_SERVICE_TOKEN"] || randomBytes(32).toString("hex");
+
   // Build the set of extra env vars to replay on the new assistant container.
   // Captured env vars serve as the base; keys already managed by
   // serviceDockerRunArgs are excluded to avoid duplicates.
   const envKeysSetByRunArgs = new Set([
+    "CES_SERVICE_TOKEN",
     "VELLUM_ASSISTANT_NAME",
     "RUNTIME_HTTP_HOST",
     "PATH",
@@ -278,9 +291,16 @@ async function upgradeDocker(
     }
   }
 
+  console.log("🔄 Migrating security files to gateway volume...");
+  await migrateGatewaySecurityFiles(res, (msg) => console.log(msg));
+
+  console.log("🔄 Migrating credential files to CES security volume...");
+  await migrateCesSecurityFiles(res, (msg) => console.log(msg));
+
   console.log("🚀 Starting upgraded containers...");
   await startContainers(
     {
+      cesServiceToken,
       extraAssistantEnv,
       gatewayPort,
       imageTags,
@@ -294,6 +314,23 @@ async function upgradeDocker(
   console.log("Waiting for assistant to become ready...");
   const ready = await waitForReady(entry.runtimeUrl);
   if (ready) {
+    // Update lockfile with new service group topology
+    const newDigests = await captureImageRefs(res);
+    const updatedEntry: AssistantEntry = {
+      ...entry,
+      serviceGroupVersion: versionTag,
+      containerInfo: {
+        assistantImage: imageTags.assistant,
+        gatewayImage: imageTags.gateway,
+        cesImage: imageTags["credential-executor"],
+        assistantDigest: newDigests?.assistant,
+        gatewayDigest: newDigests?.gateway,
+        cesDigest: newDigests?.["credential-executor"],
+        networkName: res.network,
+      },
+    };
+    saveAssistantEntry(updatedEntry);
+
     console.log(
       `\n✅ Docker assistant '${instanceName}' upgraded to ${versionTag}.`,
     );
@@ -307,6 +344,7 @@ async function upgradeDocker(
 
         await startContainers(
           {
+            cesServiceToken,
             extraAssistantEnv,
             gatewayPort,
             imageTags: previousImageRefs,
@@ -318,6 +356,19 @@ async function upgradeDocker(
 
         const rollbackReady = await waitForReady(entry.runtimeUrl);
         if (rollbackReady) {
+          // Restore previous container info in lockfile after rollback
+          if (previousImageRefs) {
+            const rolledBackEntry: AssistantEntry = {
+              ...entry,
+              containerInfo: {
+                assistantImage: previousImageRefs.assistant,
+                gatewayImage: previousImageRefs.gateway,
+                cesImage: previousImageRefs["credential-executor"],
+                networkName: res.network,
+              },
+            };
+            saveAssistantEntry(rolledBackEntry);
+          }
           console.log(
             `\n⚠️  Rolled back to previous version. Upgrade to ${versionTag} failed.`,
           );

package/src/index.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 
 import cliPkg from "../package.json";
+import { backup } from "./commands/backup";
 import { clean } from "./commands/clean";
 import { client } from "./commands/client";
 import { hatch } from "./commands/hatch";
@@ -8,6 +9,7 @@ import { login, logout, whoami } from "./commands/login";
 import { pair } from "./commands/pair";
 import { ps } from "./commands/ps";
 import { recover } from "./commands/recover";
+import { restore } from "./commands/restore";
 import { retire } from "./commands/retire";
 import { setup } from "./commands/setup";
 import { sleep } from "./commands/sleep";
@@ -26,6 +28,7 @@ import { loadGuardianToken } from "./lib/guardian-token";
 import { checkHealth } from "./lib/health-check";
 
 const commands = {
+  backup,
   clean,
   client,
   hatch,
@@ -34,6 +37,7 @@ const commands = {
   pair,
   ps,
   recover,
+  restore,
   retire,
   setup,
   sleep,
@@ -51,6 +55,7 @@ function printHelp(): void {
   console.log("Usage: vellum <command> [options]");
   console.log("");
   console.log("Commands:");
+  console.log("  backup   Export a backup of a running assistant");
   console.log("  clean    Kill orphaned vellum processes");
   console.log("  client   Connect to a hatched assistant");
   console.log("  hatch    Create a new assistant instance");
@@ -61,6 +66,7 @@ function printHelp(): void {
     "  ps       List assistants (or processes for a specific assistant)",
   );
   console.log("  recover  Restore a previously retired local assistant");
+  console.log("  restore  Restore a .vbundle backup into a running assistant");
   console.log("  retire   Delete an assistant instance");
   console.log("  setup    Configure API keys interactively");
   console.log("  sleep    Stop the assistant process");

package/src/lib/assistant-config.ts

@@ -4,6 +4,7 @@ import { join } from "path";
 
 import {
   DAEMON_INTERNAL_ASSISTANT_ID,
+  DEFAULT_CES_PORT,
   DEFAULT_DAEMON_PORT,
   DEFAULT_GATEWAY_PORT,
   DEFAULT_QDRANT_PORT,
@@ -29,11 +30,28 @@ export interface LocalInstanceResources {
   gatewayPort: number;
   /** HTTP port for the Qdrant vector store */
   qdrantPort: number;
+  /** HTTP port for the CES (Claude Extension Server) */
+  cesPort: number;
   /** Absolute path to the daemon PID file */
   pidFile: string;
   [key: string]: unknown;
 }
 
+/** Docker image metadata for the service group. Enables rollback to known-good digests. */
+export interface ContainerInfo {
+  assistantImage: string;
+  gatewayImage: string;
+  cesImage: string;
+  /** sha256 digest of the assistant image at time of hatch/upgrade */
+  assistantDigest?: string;
+  /** sha256 digest of the gateway image at time of hatch/upgrade */
+  gatewayDigest?: string;
+  /** sha256 digest of the CES image at time of hatch/upgrade */
+  cesDigest?: string;
+  /** Docker network name for the service group */
+  networkName?: string;
+}
+
 export interface AssistantEntry {
   assistantId: string;
   runtimeUrl: string;
@@ -56,6 +74,10 @@ export interface AssistantEntry {
   resources?: LocalInstanceResources;
   /** PID of the file watcher process for docker instances hatched with --watch. */
   watcherPid?: number;
+  /** Last-known version of the service group, populated at hatch and updated by health checks. */
+  serviceGroupVersion?: string;
+  /** Docker image metadata for rollback. Only present for docker topology entries. */
+  containerInfo?: ContainerInfo;
   [key: string]: unknown;
 }
 
@@ -166,6 +188,7 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
       daemonPort: DEFAULT_DAEMON_PORT,
       gatewayPort,
       qdrantPort: DEFAULT_QDRANT_PORT,
+      cesPort: DEFAULT_CES_PORT,
       pidFile: join(instanceDir, ".vellum", "vellum.pid"),
     };
     mutated = true;
@@ -198,6 +221,10 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
       res.qdrantPort = DEFAULT_QDRANT_PORT;
       mutated = true;
     }
+    if (typeof res.cesPort !== "number") {
+      res.cesPort = DEFAULT_CES_PORT;
+      mutated = true;
+    }
     if (typeof res.pidFile !== "string") {
       res.pidFile = join(res.instanceDir as string, ".vellum", "vellum.pid");
       mutated = true;
@@ -373,6 +400,7 @@ export async function allocateLocalResources(
       daemonPort: DEFAULT_DAEMON_PORT,
       gatewayPort: DEFAULT_GATEWAY_PORT,
       qdrantPort: DEFAULT_QDRANT_PORT,
+      cesPort: DEFAULT_CES_PORT,
       pidFile: join(vellumDir, "vellum.pid"),
     };
   }
@@ -423,6 +451,7 @@ export async function allocateLocalResources(
     daemonPort,
     gatewayPort,
     qdrantPort,
+    cesPort: DEFAULT_CES_PORT,
     pidFile: join(instanceDir, ".vellum", "vellum.pid"),
   };
 }

package/src/lib/aws.ts

@@ -6,7 +6,7 @@ import { buildStartupScript, watchHatching } from "../commands/hatch";
 import type { PollResult } from "../commands/hatch";
 import { saveAssistantEntry, setActiveAssistant } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
-import { GATEWAY_PORT } from "./constants";
+import { GATEWAY_PORT, PROVIDER_ENV_VAR_NAMES } from "./constants";
 import type { Species } from "./constants";
 import { leaseGuardianToken } from "./guardian-token";
 import { generateInstanceName } from "./random-name";
@@ -410,10 +410,18 @@ export async function hatchAws(
 
     const sshUser = userInfo().username;
     const hatchedBy = process.env.VELLUM_HATCHED_BY;
-    const anthropicApiKey = process.env.ANTHROPIC_API_KEY;
-    if (!anthropicApiKey) {
+    const providerApiKeys: Record<string, string> = {};
+    for (const [, envVar] of Object.entries(PROVIDER_ENV_VAR_NAMES)) {
+      const value = process.env[envVar];
+      if (value) {
+        providerApiKeys[envVar] = value;
+      }
+    }
+    if (Object.keys(providerApiKeys).length === 0) {
       console.error(
-        "Error: ANTHROPIC_API_KEY environment variable is not set.",
+        "Error: No provider API key environment variable is set. " +
+          "Set at least one of: " +
+          Object.values(PROVIDER_ENV_VAR_NAMES).join(", "),
       );
       process.exit(1);
     }
@@ -437,7 +445,7 @@ export async function hatchAws(
     const startupScript = await buildStartupScript(
       species,
       sshUser,
-      anthropicApiKey,
+      providerApiKeys,
       instanceName,
       "aws",
     );

package/src/lib/constants.ts

@@ -1,3 +1,5 @@
+import providerEnvVarsRegistry from "../../../meta/provider-env-vars.json";
+
 /**
  * Canonical internal assistant ID used as the default/fallback across the CLI
  * and daemon. Mirrors `DAEMON_INTERNAL_ASSISTANT_ID` from
@@ -14,6 +16,16 @@ export const GATEWAY_PORT = process.env.GATEWAY_PORT
 export const DEFAULT_DAEMON_PORT = 7821;
 export const DEFAULT_GATEWAY_PORT = 7830;
 export const DEFAULT_QDRANT_PORT = 6333;
+export const DEFAULT_CES_PORT = 8090;
+
+/**
+ * Environment variable names for provider API keys, keyed by provider ID.
+ * Loaded from the shared registry at `meta/provider-env-vars.json` — the
+ * single source of truth also consumed by the assistant runtime and the
+ * macOS client.
+ */
+export const PROVIDER_ENV_VAR_NAMES: Record<string, string> =
+  providerEnvVarsRegistry.providers;
 
 export const VALID_REMOTE_HOSTS = [
   "local",

package/src/lib/docker.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "crypto";
 import { chmodSync, existsSync, mkdirSync, watch as fsWatch } from "fs";
 import { arch, platform } from "os";
 import { dirname, join } from "path";
@@ -11,7 +12,7 @@ import {
   setActiveAssistant,
 } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
-import { DEFAULT_GATEWAY_PORT } from "./constants";
+import { DEFAULT_GATEWAY_PORT, PROVIDER_ENV_VAR_NAMES } from "./constants";
 import type { Species } from "./constants";
 import { leaseGuardianToken } from "./guardian-token";
 import { isVellumProcess, stopProcess } from "./process";
@@ -282,10 +283,14 @@ export function dockerResourceNames(instanceName: string) {
   return {
     assistantContainer: `${instanceName}-assistant`,
     cesContainer: `${instanceName}-credential-executor`,
+    cesSecurityVolume: `${instanceName}-ces-sec`,
+    /** @deprecated Legacy — no longer created for new instances. Retained for migration of existing instances. */
     dataVolume: `${instanceName}-data`,
     gatewayContainer: `${instanceName}-gateway`,
+    gatewaySecurityVolume: `${instanceName}-gateway-sec`,
     network: `${instanceName}-net`,
     socketVolume: `${instanceName}-socket`,
+    workspaceVolume: `${instanceName}-workspace`,
   };
 }
 
@@ -335,7 +340,13 @@ export async function retireDocker(name: string): Promise<void> {
   } catch {
     // network may not exist
   }
-  for (const vol of [res.dataVolume, res.socketVolume]) {
+  for (const vol of [
+    res.dataVolume,
+    res.socketVolume,
+    res.workspaceVolume,
+    res.cesSecurityVolume,
+    res.gatewaySecurityVolume,
+  ]) {
     try {
       await exec("docker", ["volume", "rm", vol]);
     } catch {
@@ -453,13 +464,21 @@ async function buildAllImages(
  * can be restarted independently.
  */
 export function serviceDockerRunArgs(opts: {
+  cesServiceToken?: string;
   extraAssistantEnv?: Record<string, string>;
   gatewayPort: number;
   imageTags: Record<ServiceName, string>;
   instanceName: string;
   res: ReturnType<typeof dockerResourceNames>;
 }): Record<ServiceName, () => string[]> {
-  const { extraAssistantEnv, gatewayPort, imageTags, instanceName, res } = opts;
+  const {
+    cesServiceToken,
+    extraAssistantEnv,
+    gatewayPort,
+    imageTags,
+    instanceName,
+    res,
+  } = opts;
   return {
     assistant: () => {
       const args: string[] = [
@@ -470,15 +489,27 @@ export function serviceDockerRunArgs(opts: {
         res.assistantContainer,
         `--network=${res.network}`,
         "-v",
-        `${res.dataVolume}:/data`,
+        `${res.workspaceVolume}:/workspace`,
         "-v",
         `${res.socketVolume}:/run/ces-bootstrap`,
         "-e",
         `VELLUM_ASSISTANT_NAME=${instanceName}`,
         "-e",
         "RUNTIME_HTTP_HOST=0.0.0.0",
+        "-e",
+        "WORKSPACE_DIR=/workspace",
+        "-e",
+        `CES_CREDENTIAL_URL=http://${res.cesContainer}:8090`,
+        "-e",
+        `GATEWAY_INTERNAL_URL=http://${res.gatewayContainer}:${GATEWAY_INTERNAL_PORT}`,
       ];
-      for (const envVar of ["ANTHROPIC_API_KEY", "VELLUM_PLATFORM_URL"]) {
+      if (cesServiceToken) {
+        args.push("-e", `CES_SERVICE_TOKEN=${cesServiceToken}`);
+      }
+      for (const envVar of [
+        ...Object.values(PROVIDER_ENV_VAR_NAMES),
+        "VELLUM_PLATFORM_URL",
+      ]) {
         if (process.env[envVar]) {
           args.push("-e", `${envVar}=${process.env[envVar]}`);
         }
@@ -501,9 +532,13 @@ export function serviceDockerRunArgs(opts: {
       "-p",
       `${gatewayPort}:${GATEWAY_INTERNAL_PORT}`,
       "-v",
-      `${res.dataVolume}:/data`,
+      `${res.workspaceVolume}:/workspace`,
+      "-v",
+      `${res.gatewaySecurityVolume}:/gateway-security`,
+      "-e",
+      "WORKSPACE_DIR=/workspace",
       "-e",
-      "BASE_DATA_DIR=/data",
+      "GATEWAY_SECURITY_DIR=/gateway-security",
       "-e",
       `GATEWAY_PORT=${GATEWAY_INTERNAL_PORT}`,
       "-e",
@@ -512,6 +547,11 @@ export function serviceDockerRunArgs(opts: {
       `RUNTIME_HTTP_PORT=${ASSISTANT_INTERNAL_PORT}`,
       "-e",
       "RUNTIME_PROXY_ENABLED=true",
+      "-e",
+      `CES_CREDENTIAL_URL=http://${res.cesContainer}:8090`,
+      ...(cesServiceToken
+        ? ["-e", `CES_SERVICE_TOKEN=${cesServiceToken}`]
+        : []),
       imageTags.gateway,
     ],
     "credential-executor": () => [
@@ -520,21 +560,171 @@ export function serviceDockerRunArgs(opts: {
       "-d",
       "--name",
       res.cesContainer,
+      `--network=${res.network}`,
       "-v",
       `${res.socketVolume}:/run/ces-bootstrap`,
       "-v",
-      `${res.dataVolume}:/data:ro`,
+      `${res.workspaceVolume}:/workspace:ro`,
+      "-v",
+      `${res.cesSecurityVolume}:/ces-security`,
       "-e",
       "CES_MODE=managed",
       "-e",
+      "WORKSPACE_DIR=/workspace",
+      "-e",
       "CES_BOOTSTRAP_SOCKET_DIR=/run/ces-bootstrap",
       "-e",
-      "CES_ASSISTANT_DATA_MOUNT=/data",
+      "CREDENTIAL_SECURITY_DIR=/ces-security",
+      ...(cesServiceToken
+        ? ["-e", `CES_SERVICE_TOKEN=${cesServiceToken}`]
+        : []),
       imageTags["credential-executor"],
     ],
   };
 }
 
+/**
+ * Check whether a Docker volume exists.
+ * Returns true if the volume exists, false otherwise.
+ */
+async function dockerVolumeExists(volumeName: string): Promise<boolean> {
+  try {
+    await execOutput("docker", ["volume", "inspect", volumeName]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Migrate trust.json and actor-token-signing-key from the data volume
+ * (old location: /data/.vellum/protected/) to the gateway security volume
+ * (new location: /gateway-security/).
+ *
+ * Uses a temporary busybox container that mounts both volumes. The migration
+ * is idempotent: it only copies a file when the source exists on the data
+ * volume and the destination does not yet exist on the gateway security volume.
+ *
+ * Skips migration entirely if the data volume does not exist (new instances
+ * no longer create one).
+ */
+export async function migrateGatewaySecurityFiles(
+  res: ReturnType<typeof dockerResourceNames>,
+  log: (msg: string) => void,
+): Promise<void> {
+  // New instances don't have a data volume — nothing to migrate.
+  if (!(await dockerVolumeExists(res.dataVolume))) {
+    log("   No data volume found — skipping gateway security migration.");
+    return;
+  }
+
+  const migrationContainer = `${res.gatewayContainer}-migration`;
+  const filesToMigrate = ["trust.json", "actor-token-signing-key"];
+
+  // Remove any leftover migration container from a previous interrupted run.
+  try {
+    await exec("docker", ["rm", "-f", migrationContainer]);
+  } catch {
+    // container may not exist
+  }
+
+  for (const fileName of filesToMigrate) {
+    const src = `/data/.vellum/protected/${fileName}`;
+    const dst = `/gateway-security/${fileName}`;
+
+    try {
+      // Run a busybox container that checks source exists and destination
+      // does not, then copies. The shell exits 0 whether or not a copy
+      // happens, so the migration is always safe to re-run.
+      await exec("docker", [
+        "run",
+        "--rm",
+        "--name",
+        migrationContainer,
+        "-v",
+        `${res.dataVolume}:/data:ro`,
+        "-v",
+        `${res.gatewaySecurityVolume}:/gateway-security`,
+        "busybox",
+        "sh",
+        "-c",
+        `if [ -f "${src}" ] && [ ! -f "${dst}" ]; then cp "${src}" "${dst}" && echo "migrated"; else echo "skipped"; fi`,
+      ]);
+      log(`   ${fileName}: checked`);
+    } catch (err) {
+      // Non-fatal — log and continue. The gateway will create fresh files
+      // if they don't exist.
+      const message = err instanceof Error ? err.message : String(err);
+      log(`   ${fileName}: migration failed (${message}), continuing...`);
+    }
+  }
+}
+
+/**
+ * Migrate keys.enc and store.key from the data volume
+ * (old location: /data/.vellum/protected/) to the CES security volume
+ * (new location: /ces-security/).
+ *
+ * Uses a temporary busybox container that mounts both volumes. The migration
+ * is idempotent: it only copies a file when the source exists on the data
+ * volume and the destination does not yet exist on the CES security volume.
+ * Migrated files are chowned to 1001:1001 (the CES service user).
+ *
+ * Skips migration entirely if the data volume does not exist (new instances
+ * no longer create one).
+ */
+export async function migrateCesSecurityFiles(
+  res: ReturnType<typeof dockerResourceNames>,
+  log: (msg: string) => void,
+): Promise<void> {
+  // New instances don't have a data volume — nothing to migrate.
+  if (!(await dockerVolumeExists(res.dataVolume))) {
+    log("   No data volume found — skipping CES security migration.");
+    return;
+  }
+
+  const migrationContainer = `${res.cesContainer}-migration`;
+  const filesToMigrate = ["keys.enc", "store.key"];
+
+  // Remove any leftover migration container from a previous interrupted run.
+  try {
+    await exec("docker", ["rm", "-f", migrationContainer]);
+  } catch {
+    // container may not exist
+  }
+
+  for (const fileName of filesToMigrate) {
+    const src = `/data/.vellum/protected/${fileName}`;
+    const dst = `/ces-security/${fileName}`;
+
+    try {
+      // Run a busybox container that checks source exists and destination
+      // does not, then copies and sets ownership. The shell exits 0 whether
+      // or not a copy happens, so the migration is always safe to re-run.
+      await exec("docker", [
+        "run",
+        "--rm",
+        "--name",
+        migrationContainer,
+        "-v",
+        `${res.dataVolume}:/data:ro`,
+        "-v",
+        `${res.cesSecurityVolume}:/ces-security`,
+        "busybox",
+        "sh",
+        "-c",
+        `if [ -f "${src}" ] && [ ! -f "${dst}" ]; then cp "${src}" "${dst}" && chown 1001:1001 "${dst}" && echo "migrated"; else echo "skipped"; fi`,
+      ]);
+      log(`   ${fileName}: checked`);
+    } catch (err) {
+      // Non-fatal — log and continue. The CES will start without
+      // credentials if they don't exist.
+      const message = err instanceof Error ? err.message : String(err);
+      log(`   ${fileName}: migration failed (${message}), continuing...`);
+    }
+  }
+}
+
 /** The order in which services must be started. */
 export const SERVICE_START_ORDER: ServiceName[] = [
   "assistant",
@@ -545,6 +735,7 @@ export const SERVICE_START_ORDER: ServiceName[] = [
 /** Start all three containers in dependency order. */
 export async function startContainers(
   opts: {
+    cesServiceToken?: string;
     extraAssistantEnv?: Record<string, string>;
     gatewayPort: number;
     imageTags: Record<ServiceName, string>;
@@ -573,7 +764,11 @@ export async function stopContainers(
 export async function sleepContainers(
   res: ReturnType<typeof dockerResourceNames>,
 ): Promise<void> {
-  for (const container of [res.cesContainer, res.gatewayContainer, res.assistantContainer]) {
+  for (const container of [
+    res.cesContainer,
+    res.gatewayContainer,
+    res.assistantContainer,
+  ]) {
     try {
       await exec("docker", ["stop", container]);
     } catch {
@@ -586,7 +781,11 @@ export async function sleepContainers(
 export async function wakeContainers(
   res: ReturnType<typeof dockerResourceNames>,
 ): Promise<void> {
-  for (const container of [res.assistantContainer, res.gatewayContainer, res.cesContainer]) {
+  for (const container of [
+    res.assistantContainer,
+    res.gatewayContainer,
+    res.cesContainer,
+  ]) {
     await exec("docker", ["start", container]);
   }
 }
@@ -867,10 +1066,18 @@ export async function hatchDocker(
 
     log("📁 Creating network and volumes...");
     await exec("docker", ["network", "create", res.network]);
-    await exec("docker", ["volume", "create", res.dataVolume]);
     await exec("docker", ["volume", "create", res.socketVolume]);
+    await exec("docker", ["volume", "create", res.workspaceVolume]);
+    await exec("docker", ["volume", "create", res.cesSecurityVolume]);
+    await exec("docker", ["volume", "create", res.gatewaySecurityVolume]);
+
+    const cesServiceToken = randomBytes(32).toString("hex");
+    await startContainers(
+      { cesServiceToken, gatewayPort, imageTags, instanceName, res },
+      log,
+    );
 
-    await startContainers({ gatewayPort, imageTags, instanceName, res }, log);
+    const imageDigests = await captureImageRefs(res);
 
     const runtimeUrl = `http://localhost:${gatewayPort}`;
     const dockerEntry: AssistantEntry = {
@@ -880,6 +1087,16 @@ export async function hatchDocker(
       species,
       hatchedAt: new Date().toISOString(),
       volume: res.dataVolume,
+      serviceGroupVersion: cliPkg.version ? `v${cliPkg.version}` : undefined,
+      containerInfo: {
+        assistantImage: imageTags.assistant,
+        gatewayImage: imageTags.gateway,
+        cesImage: imageTags["credential-executor"],
+        assistantDigest: imageDigests?.assistant,
+        gatewayDigest: imageDigests?.gateway,
+        cesDigest: imageDigests?.["credential-executor"],
+        networkName: res.network,
+      },
     };
     saveAssistantEntry(dockerEntry);
     setActiveAssistant(instanceName);

package/src/lib/gcp.ts

@@ -4,7 +4,11 @@ import { join } from "path";
 
 import { saveAssistantEntry, setActiveAssistant } from "./assistant-config";
 import type { AssistantEntry } from "./assistant-config";
-import { FIREWALL_TAG, GATEWAY_PORT } from "./constants";
+import {
+  FIREWALL_TAG,
+  GATEWAY_PORT,
+  PROVIDER_ENV_VAR_NAMES,
+} from "./constants";
 import type { Species } from "./constants";
 import { leaseGuardianToken } from "./guardian-token";
 import { generateInstanceName } from "./random-name";
@@ -448,7 +452,7 @@ export async function hatchGcp(
   buildStartupScript: (
     species: Species,
     sshUser: string,
-    anthropicApiKey: string,
+    providerApiKeys: Record<string, string>,
     instanceName: string,
     cloud: "gcp",
   ) => Promise<string>,
@@ -500,17 +504,25 @@ export async function hatchGcp(
 
     const sshUser = userInfo().username;
     const hatchedBy = process.env.VELLUM_HATCHED_BY;
-    const anthropicApiKey = process.env.ANTHROPIC_API_KEY;
-    if (!anthropicApiKey) {
+    const providerApiKeys: Record<string, string> = {};
+    for (const [, envVar] of Object.entries(PROVIDER_ENV_VAR_NAMES)) {
+      const value = process.env[envVar];
+      if (value) {
+        providerApiKeys[envVar] = value;
+      }
+    }
+    if (Object.keys(providerApiKeys).length === 0) {
       console.error(
-        "Error: ANTHROPIC_API_KEY environment variable is not set.",
+        "Error: No provider API key environment variable is set. " +
+          "Set at least one of: " +
+          Object.values(PROVIDER_ENV_VAR_NAMES).join(", "),
       );
       process.exit(1);
     }
     const startupScript = await buildStartupScript(
       species,
       sshUser,
-      anthropicApiKey,
+      providerApiKeys,
       instanceName,
       "gcp",
     );