@vellumai/cli 0.5.4 → 0.5.6

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/knip.json

@@ -2,7 +2,8 @@
   "entry": [
     "src/**/*.test.ts",
     "src/**/__tests__/**/*.ts",
-    "src/adapters/openclaw-http-server.ts"
+    "src/adapters/openclaw-http-server.ts",
+    "src/lib/version-compat.ts"
   ],
   "project": ["src/**/*.ts", "src/**/*.tsx"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "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/__tests__/health-check.test.ts

@@ -10,6 +10,7 @@ describe("checkHealth", () => {
   test("returns unreachable for non-existent host", async () => {
     const result = await checkHealth("http://127.0.0.1:1");
     expect(["unreachable", "timeout"]).toContain(result.status);
+    expect(result.version).toBeUndefined();
   });
 
   test("returns healthy for a mock healthy endpoint", async () => {
@@ -24,6 +25,24 @@ describe("checkHealth", () => {
       const result = await checkHealth(`http://localhost:${server.port}`);
       expect(result.status).toBe("healthy");
       expect(result.detail).toBeNull();
+      expect(result.version).toBeUndefined();
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("returns version when present in response", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch() {
+        return Response.json({ status: "healthy", version: "1.2.3" });
+      },
+    });
+
+    try {
+      const result = await checkHealth(`http://localhost:${server.port}`);
+      expect(result.status).toBe("healthy");
+      expect(result.version).toBe("1.2.3");
     } finally {
       server.stop(true);
     }
@@ -33,7 +52,11 @@ describe("checkHealth", () => {
     const server = Bun.serve({
       port: 0,
       fetch() {
-        return Response.json({ status: "degraded", message: "high latency" });
+        return Response.json({
+          status: "degraded",
+          message: "high latency",
+          version: "0.9.0",
+        });
       },
     });
 
@@ -41,6 +64,7 @@ describe("checkHealth", () => {
       const result = await checkHealth(`http://localhost:${server.port}`);
       expect(result.status).toBe("degraded");
       expect(result.detail).toBe("high latency");
+      expect(result.version).toBe("0.9.0");
     } finally {
       server.stop(true);
     }
@@ -57,6 +81,7 @@ describe("checkHealth", () => {
     try {
       const result = await checkHealth(`http://localhost:${server.port}`);
       expect(result.status).toBe("error (500)");
+      expect(result.version).toBeUndefined();
     } finally {
       server.stop(true);
     }

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/ps.ts

@@ -4,6 +4,7 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
+  updateServiceGroupVersion,
   type AssistantEntry,
 } from "../lib/assistant-config";
 import { loadGuardianToken } from "../lib/guardian-token";
@@ -424,7 +425,7 @@ async function listAllAssistants(): Promise<void> {
       // hitting the health endpoint. If the PID file is missing or the
       // process isn't running, the assistant is sleeping — skip the
       // network health check to avoid a misleading "unreachable" status.
-      let health: { status: string; detail: string | null };
+      let health: { status: string; detail: string | null; version?: string };
       const resources = a.resources;
       if (a.cloud === "local" && resources) {
         const pid = readPidFile(resources.pidFile);
@@ -451,6 +452,10 @@ async function listAllAssistants(): Promise<void> {
         health = await checkHealth(a.localUrl ?? a.runtimeUrl, token);
       }
 
+      if (health.status === "healthy" && health.version) {
+        updateServiceGroupVersion(a.assistantId, health.version);
+      }
+
       const infoParts = [a.runtimeUrl];
       if (a.cloud) infoParts.push(`cloud: ${a.cloud}`);
       if (a.species) infoParts.push(`species: ${a.species}`);