@vellumai/cli 0.5.11 → 0.5.13

package/package.json

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

package/src/commands/backup.ts

@@ -66,7 +66,7 @@ export async function backup(): Promise<void> {
   const cloud =
     entry.cloud || (entry.project ? "gcp" : entry.sshUser ? "custom" : "local");
   if (cloud === "vellum") {
-    await backupPlatform(name, outputArg);
+    await backupPlatform(name, outputArg, entry.runtimeUrl);
     return;
   }
 
@@ -184,7 +184,11 @@ export async function backup(): Promise<void> {
 // Platform (Vellum-hosted) backup via Django async migration export
 // ---------------------------------------------------------------------------
 
-async function backupPlatform(name: string, outputArg?: string): Promise<void> {
+async function backupPlatform(
+  name: string,
+  outputArg?: string,
+  runtimeUrl?: string,
+): Promise<void> {
   // Step 1 — Authenticate
   const token = readPlatformToken();
   if (!token) {
@@ -194,7 +198,7 @@ async function backupPlatform(name: string, outputArg?: string): Promise<void> {
 
   let orgId: string;
   try {
-    orgId = await fetchOrganizationId(token);
+    orgId = await fetchOrganizationId(token, runtimeUrl);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("401") || msg.includes("403")) {
@@ -207,7 +211,12 @@ async function backupPlatform(name: string, outputArg?: string): Promise<void> {
   // Step 2 — Initiate export job
   let jobId: string;
   try {
-    const result = await platformInitiateExport(token, orgId, "CLI backup");
+    const result = await platformInitiateExport(
+      token,
+      orgId,
+      "CLI backup",
+      runtimeUrl,
+    );
     jobId = result.jobId;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -235,7 +244,7 @@ async function backupPlatform(name: string, outputArg?: string): Promise<void> {
   while (Date.now() < deadline) {
     let status: { status: string; downloadUrl?: string; error?: string };
     try {
-      status = await platformPollExportStatus(jobId, token, orgId);
+      status = await platformPollExportStatus(jobId, token, orgId, runtimeUrl);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       // Let non-transient errors (e.g. 404 "job not found") propagate immediately

package/src/commands/hatch.ts

@@ -47,7 +47,11 @@ import {
   stopLocalProcesses,
 } from "../lib/local";
 import { maybeStartNgrokTunnel } from "../lib/ngrok";
-import { getPlatformUrl } from "../lib/platform-client";
+import {
+  getPlatformUrl,
+  hatchAssistant,
+  readPlatformToken,
+} from "../lib/platform-client";
 import { httpHealthCheck } from "../lib/http-client";
 import { detectOrphanedProcesses } from "../lib/orphan-detection";
 import { isProcessAlive, stopProcess } from "../lib/process";
@@ -237,7 +241,7 @@ function parseArgs(): HatchArgs {
       console.log("  -d                        Run in detached mode");
       console.log("  --name <name>             Custom instance name");
       console.log(
-        "  --remote <host>           Remote host (local, gcp, aws, docker, custom)",
+        "  --remote <host>           Remote host (local, gcp, aws, docker, custom, vellum)",
       );
       console.log(
         "  --restart                 Restart processes without onboarding side effects",
@@ -943,6 +947,48 @@ export async function hatch(): Promise<void> {
     return;
   }
 
+  if (remote === "vellum") {
+    await hatchVellumPlatform();
+    return;
+  }
+
   console.error(`Error: Remote host '${remote}' is not yet supported.`);
   process.exit(1);
 }
+
+async function hatchVellumPlatform(): Promise<void> {
+  const token = readPlatformToken();
+  if (!token) {
+    console.error("Not logged in. Run `vellum login --token <token>` first.");
+    process.exit(1);
+  }
+
+  const config = SPECIES_CONFIG.vellum;
+  console.log("");
+  for (const line of config.art) {
+    console.log(`   ${line}`);
+  }
+  console.log("");
+  console.log("   Hatching assistant on Vellum platform...");
+  console.log("");
+
+  const result = await hatchAssistant(token);
+
+  const platformUrl = getPlatformUrl();
+
+  saveAssistantEntry({
+    assistantId: result.id,
+    runtimeUrl: platformUrl,
+    cloud: "vellum",
+    species: "vellum",
+    hatchedAt: new Date().toISOString(),
+  });
+  setActiveAssistant(result.id);
+
+  console.log(`   ${config.hatchedEmoji}  Your assistant has hatched!`);
+  console.log("");
+  console.log(`   ID:     ${result.id}`);
+  console.log(`   Name:   ${result.name}`);
+  console.log(`   Status: ${result.status}`);
+  console.log("");
+}

package/src/commands/restore.ts

@@ -179,7 +179,7 @@ async function restorePlatform(
 
   let orgId: string;
   try {
-    orgId = await fetchOrganizationId(token);
+    orgId = await fetchOrganizationId(token, entry.runtimeUrl);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("401") || msg.includes("403")) {
@@ -206,6 +206,7 @@ async function restorePlatform(
         new Uint8Array(bundleData),
         token,
         orgId,
+        entry.runtimeUrl,
       );
     } catch (err) {
       if (err instanceof Error && err.name === "TimeoutError") {
@@ -315,7 +316,12 @@ async function restorePlatform(
     );
 
     try {
-      await rollbackPlatformAssistant(token, orgId, opts.version);
+      await rollbackPlatformAssistant(
+        token,
+        orgId,
+        opts.version,
+        entry.runtimeUrl,
+      );
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       if (msg.includes("401") || msg.includes("403")) {
@@ -340,6 +346,7 @@ async function restorePlatform(
       new Uint8Array(bundleData),
       token,
       orgId,
+      entry.runtimeUrl,
     );
   } catch (err) {
     if (err instanceof Error && err.name === "TimeoutError") {

package/src/commands/retire.ts

@@ -197,7 +197,10 @@ async function retireCustom(entry: AssistantEntry): Promise<void> {
   console.log(`\u2705 Custom instance retired.`);
 }
 
-async function retireVellum(assistantId: string): Promise<void> {
+async function retireVellum(
+  assistantId: string,
+  runtimeUrl?: string,
+): Promise<void> {
   console.log("\u{1F5D1}\ufe0f  Retiring platform-hosted instance...\n");
 
   const token = readPlatformToken();
@@ -208,9 +211,10 @@ async function retireVellum(assistantId: string): Promise<void> {
     process.exit(1);
   }
 
-  const orgId = await fetchOrganizationId(token);
+  const orgId = await fetchOrganizationId(token, runtimeUrl);
 
-  const url = `${getPlatformUrl()}/v1/assistants/${encodeURIComponent(assistantId)}/retire/`;
+  const platformUrl = runtimeUrl || getPlatformUrl();
+  const url = `${platformUrl}/v1/assistants/${encodeURIComponent(assistantId)}/retire/`;
   const response = await fetch(url, {
     method: "DELETE",
     headers: {
@@ -343,7 +347,7 @@ async function retireInner(): Promise<void> {
   } else if (cloud === "custom") {
     await retireCustom(entry);
   } else if (cloud === "vellum") {
-    await retireVellum(entry.assistantId);
+    await retireVellum(entry.assistantId, entry.runtimeUrl);
   } else {
     console.error(`Error: Unknown cloud type '${cloud}'.`);
     process.exit(1);

package/src/commands/rollback.ts

@@ -185,7 +185,7 @@ async function rollbackPlatformViaEndpoint(
 
   let orgId: string;
   try {
-    orgId = await fetchOrganizationId(token);
+    orgId = await fetchOrganizationId(token, entry.runtimeUrl);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("401") || msg.includes("403")) {
@@ -206,7 +206,12 @@ async function rollbackPlatformViaEndpoint(
 
   let result: { detail: string; version: string | null };
   try {
-    result = await rollbackPlatformAssistant(token, orgId, version);
+    result = await rollbackPlatformAssistant(
+      token,
+      orgId,
+      version,
+      entry.runtimeUrl,
+    );
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err);
 

package/src/commands/upgrade.ts

@@ -729,9 +729,9 @@ async function upgradePlatform(
     process.exit(1);
   }
 
-  const orgId = await fetchOrganizationId(token);
+  const orgId = await fetchOrganizationId(token, entry.runtimeUrl);
 
-  const url = `${getPlatformUrl()}/v1/assistants/upgrade/`;
+  const url = `${entry.runtimeUrl || getPlatformUrl()}/v1/assistants/upgrade/`;
   const body: { assistant_id?: string; version?: string } = {
     assistant_id: entry.assistantId,
   };

package/src/lib/assistant-config.ts

@@ -16,6 +16,7 @@ import {
   DEFAULT_DAEMON_PORT,
   DEFAULT_GATEWAY_PORT,
   DEFAULT_QDRANT_PORT,
+  LOCKFILE_NAMES,
 } from "./constants.js";
 import { probePort } from "./port-probe.js";
 
@@ -119,10 +120,7 @@ function getLockfileDir(): string {
 
 function readLockfile(): LockfileData {
   const base = getLockfileDir();
-  const candidates = [
-    join(base, ".vellum.lock.json"),
-    join(base, ".vellum.lockfile.json"),
-  ];
+  const candidates = LOCKFILE_NAMES.map((name) => join(base, name));
   for (const lockfilePath of candidates) {
     if (!existsSync(lockfilePath)) continue;
     try {
@@ -139,7 +137,7 @@ function readLockfile(): LockfileData {
 }
 
 function writeLockfile(data: LockfileData): void {
-  const lockfilePath = join(getLockfileDir(), ".vellum.lock.json");
+  const lockfilePath = join(getLockfileDir(), LOCKFILE_NAMES[0]);
   const tmpPath = `${lockfilePath}.${randomBytes(4).toString("hex")}.tmp`;
   try {
     writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");

package/src/lib/constants.ts

@@ -18,6 +18,16 @@ export const DEFAULT_GATEWAY_PORT = 7830;
 export const DEFAULT_QDRANT_PORT = 6333;
 export const DEFAULT_CES_PORT = 8090;
 
+/**
+ * Lockfile candidate filenames, checked in priority order.
+ * `.vellum.lock.json` is the current name; `.vellum.lockfile.json` is the
+ * legacy name kept for backwards compatibility with older installs.
+ */
+export const LOCKFILE_NAMES = [
+  ".vellum.lock.json",
+  ".vellum.lockfile.json",
+] as const;
+
 /**
  * Environment variable names for provider API keys, keyed by provider ID.
  * Loaded from the shared registry at `meta/provider-env-vars.json` — the
@@ -33,6 +43,7 @@ export const VALID_REMOTE_HOSTS = [
   "aws",
   "docker",
   "custom",
+  "vellum",
 ] as const;
 export type RemoteHost = (typeof VALID_REMOTE_HOSTS)[number];
 export const VALID_SPECIES = ["openclaw", "vellum"] as const;

package/src/lib/health-check.ts

@@ -28,7 +28,7 @@ export async function checkManagedHealth(
   let orgId: string;
   try {
     const { fetchOrganizationId } = await import("./platform-client.js");
-    orgId = await fetchOrganizationId(token);
+    orgId = await fetchOrganizationId(token, runtimeUrl);
   } catch (err) {
     return {
       status: "error (auth)",

package/src/lib/ngrok.ts

@@ -235,6 +235,13 @@ function hasNonNgrokIngressUrl(): boolean {
 export async function maybeStartNgrokTunnel(
   targetPort: number,
 ): Promise<ChildProcess | null> {
+  // Managed/containerized deployments route webhooks through the platform's
+  // callback proxy. ngrok is not needed and would not be reachable from the
+  // platform anyway — skip it entirely.
+  const isContainerized =
+    process.env.IS_CONTAINERIZED === "true" ||
+    process.env.IS_CONTAINERIZED === "1";
+  if (isContainerized) return null;
   if (!hasWebhookIntegrationsConfigured()) return null;
   if (hasNonNgrokIngressUrl()) return null;
 

package/src/lib/platform-client.ts

@@ -65,6 +65,67 @@ export function clearPlatformToken(): void {
   }
 }
 
+const VAK_PREFIX = "vak_";
+
+/**
+ * Returns the appropriate auth header for the given platform token.
+ *
+ * - `vak_`-prefixed tokens are long-lived platform API keys and use
+ *   `Authorization: Bearer`.
+ * - All other tokens are allauth session tokens and use `X-Session-Token`.
+ */
+export function authHeaders(token: string): Record<string, string> {
+  if (token.startsWith(VAK_PREFIX)) {
+    return { Authorization: `Bearer ${token}` };
+  }
+  return { "X-Session-Token": token };
+}
+
+export interface HatchedAssistant {
+  id: string;
+  name: string;
+  status: string;
+}
+
+export async function hatchAssistant(token: string): Promise<HatchedAssistant> {
+  const url = `${getPlatformUrl()}/v1/assistants/hatch/`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...authHeaders(token),
+    },
+    body: JSON.stringify({}),
+  });
+
+  if (response.ok) {
+    return (await response.json()) as HatchedAssistant;
+  }
+
+  if (response.status === 401 || response.status === 403) {
+    const detail = (await response.json().catch(() => ({}))) as {
+      detail?: string;
+    };
+    throw new Error(
+      detail.detail ??
+        "Invalid or expired token. Run `vellum login` to re-authenticate.",
+    );
+  }
+
+  if (response.status === 402) {
+    throw new Error("Insufficient balance to hatch a new assistant.");
+  }
+
+  const errorBody = (await response.json().catch(() => ({}))) as {
+    detail?: string;
+  };
+  throw new Error(
+    errorBody.detail ??
+      `Platform API error: ${response.status} ${response.statusText}`,
+  );
+}
+
 export interface PlatformUser {
   id: string;
   email: string;
@@ -75,16 +136,19 @@ interface OrganizationListResponse {
   results: { id: string; name: string }[];
 }
 
-export async function fetchOrganizationId(token: string): Promise<string> {
-  const platformUrl = getPlatformUrl();
-  const url = `${platformUrl}/v1/organizations/`;
+export async function fetchOrganizationId(
+  token: string,
+  platformUrl?: string,
+): Promise<string> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const url = `${resolvedUrl}/v1/organizations/`;
   const response = await fetch(url, {
     headers: { "X-Session-Token": token },
   });
 
   if (!response.ok) {
     throw new Error(
-      `Failed to fetch organizations from ${platformUrl} (${response.status}). Try logging in again.`,
+      `Failed to fetch organizations from ${resolvedUrl} (${response.status}). Try logging in again.`,
     );
   }
 
@@ -107,8 +171,12 @@ interface AllauthSessionResponse {
   };
 }
 
-export async function fetchCurrentUser(token: string): Promise<PlatformUser> {
-  const url = `${getPlatformUrl()}/_allauth/app/v1/auth/session`;
+export async function fetchCurrentUser(
+  token: string,
+  platformUrl?: string,
+): Promise<PlatformUser> {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const url = `${resolvedUrl}/_allauth/app/v1/auth/session`;
   const response = await fetch(url, {
     headers: { "X-Session-Token": token },
   });
@@ -138,9 +206,10 @@ export async function rollbackPlatformAssistant(
   token: string,
   orgId: string,
   version?: string,
+  platformUrl?: string,
 ): Promise<{ detail: string; version: string | null }> {
-  const platformUrl = getPlatformUrl();
-  const response = await fetch(`${platformUrl}/v1/assistants/rollback/`, {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const response = await fetch(`${resolvedUrl}/v1/assistants/rollback/`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
@@ -182,9 +251,10 @@ export async function platformInitiateExport(
   token: string,
   orgId: string,
   description?: string,
+  platformUrl?: string,
 ): Promise<{ jobId: string; status: string }> {
-  const platformUrl = getPlatformUrl();
-  const response = await fetch(`${platformUrl}/v1/migrations/export/`, {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const response = await fetch(`${resolvedUrl}/v1/migrations/export/`, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
@@ -215,10 +285,11 @@ export async function platformPollExportStatus(
   jobId: string,
   token: string,
   orgId: string,
+  platformUrl?: string,
 ): Promise<{ status: string; downloadUrl?: string; error?: string }> {
-  const platformUrl = getPlatformUrl();
+  const resolvedUrl = platformUrl || getPlatformUrl();
   const response = await fetch(
-    `${platformUrl}/v1/migrations/export/${jobId}/status/`,
+    `${resolvedUrl}/v1/migrations/export/${jobId}/status/`,
     {
       headers: {
         "X-Session-Token": token,
@@ -269,10 +340,11 @@ export async function platformImportPreflight(
   bundleData: Uint8Array<ArrayBuffer>,
   token: string,
   orgId: string,
+  platformUrl?: string,
 ): Promise<{ statusCode: number; body: Record<string, unknown> }> {
-  const platformUrl = getPlatformUrl();
+  const resolvedUrl = platformUrl || getPlatformUrl();
   const response = await fetch(
-    `${platformUrl}/v1/migrations/import-preflight/`,
+    `${resolvedUrl}/v1/migrations/import-preflight/`,
     {
       method: "POST",
       headers: {
@@ -296,9 +368,10 @@ export async function platformImportBundle(
   bundleData: Uint8Array<ArrayBuffer>,
   token: string,
   orgId: string,
+  platformUrl?: string,
 ): Promise<{ statusCode: number; body: Record<string, unknown> }> {
-  const platformUrl = getPlatformUrl();
-  const response = await fetch(`${platformUrl}/v1/migrations/import/`, {
+  const resolvedUrl = platformUrl || getPlatformUrl();
+  const response = await fetch(`${resolvedUrl}/v1/migrations/import/`, {
     method: "POST",
     headers: {
       "Content-Type": "application/octet-stream",