@vellumai/cli 0.5.3 → 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.3",
+  "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/sleep.ts

@@ -3,6 +3,7 @@ import { join } from "path";
 
 import { resolveTargetAssistant } from "../lib/assistant-config.js";
 import type { AssistantEntry } from "../lib/assistant-config.js";
+import { dockerResourceNames, sleepContainers } from "../lib/docker.js";
 import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
 
 const ACTIVE_CALL_LEASES_FILE = "active-call-leases.json";
@@ -64,9 +65,16 @@ export async function sleep(): Promise<void> {
   const nameArg = args.find((a) => !a.startsWith("-"));
   const entry = resolveTargetAssistant(nameArg);
 
+  if (entry.cloud === "docker") {
+    const res = dockerResourceNames(entry.assistantId);
+    await sleepContainers(res);
+    console.log("Docker containers stopped.");
+    return;
+  }
+
   if (entry.cloud && entry.cloud !== "local") {
     console.error(
-      `Error: 'vellum sleep' only works with local assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,
+      `Error: 'vellum sleep' only works with local and docker assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,
     );
     process.exit(1);
   }

package/src/commands/ssh.ts

@@ -5,6 +5,7 @@ import {
   loadLatestAssistant,
 } from "../lib/assistant-config";
 import type { AssistantEntry } from "../lib/assistant-config";
+import { dockerResourceNames } from "../lib/docker";
 
 const SSH_OPTS = [
   "-o",
@@ -82,7 +83,16 @@ export async function ssh(): Promise<void> {
 
   let child;
 
-  if (cloud === "gcp") {
+  if (cloud === "docker") {
+    const res = dockerResourceNames(entry.assistantId);
+    console.log(`🔗 Connecting to ${entry.assistantId} via docker exec...\n`);
+
+    child = spawn(
+      "docker",
+      ["exec", "-it", res.assistantContainer, "/bin/sh"],
+      { stdio: "inherit" },
+    );
+  } else if (cloud === "gcp") {
     const project = entry.project;
     const zone = entry.zone;
     if (!project || !zone) {