@vellumai/cli 0.1.8 → 0.1.10

package/README.md

@@ -39,7 +39,7 @@ vellum-cli hatch [species] [options]
 
 #### Remote Targets
 
-- **`local`** -- Starts a local daemon on your machine via `bunx vellum daemon start`.
+- **`local`** -- Starts the local daemon and local gateway. Gateway source resolution order is: `VELLUM_GATEWAY_DIR` override, repo source tree, then installed `@vellumai/vellum-gateway` package.
 - **`gcp`** -- Creates a GCP Compute Engine VM (`e2-standard-4`: 4 vCPUs, 16 GB) with a startup script that bootstraps the assistant. Requires `gcloud` authentication and `GCP_PROJECT` / `GCP_DEFAULT_ZONE` environment variables.
 - **`aws`** -- Provisions an AWS instance.
 - **`custom`** -- Provisions on an arbitrary SSH host. Set `VELLUM_CUSTOM_HOST` (e.g. `user@hostname`) to specify the target.
@@ -52,6 +52,8 @@ vellum-cli hatch [species] [options]
 | `GCP_PROJECT`         | `gcp`        | GCP project ID. Falls back to the active `gcloud` project. |
 | `GCP_DEFAULT_ZONE`    | `gcp`        | GCP zone for the compute instance. |
 | `VELLUM_CUSTOM_HOST`  | `custom`     | SSH host in `user@hostname` format. |
+| `VELLUM_GATEWAY_DIR`  | `local`      | Optional absolute path to a local gateway source directory to run instead of the packaged gateway. |
+| `INGRESS_PUBLIC_BASE_URL` | `local` | Optional fallback public ingress URL when `ingress.publicBaseUrl` is not set in workspace config. |
 
 #### Examples
 

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "bin": {
     "vellum-cli": "./src/index.ts"
   },
   "scripts": {
-    "bump": "bun run scripts/bump.ts",
     "lint": "eslint",
     "typecheck": "bunx tsc --noEmit"
   },

package/src/adapters/install.sh

@@ -79,6 +79,23 @@ ensure_bun() {
     success "bun installed ($(bun --version))"
 }
 
+install_vellum() {
+    if command -v vellum >/dev/null 2>&1; then
+        info "Updating vellum to latest..."
+        bun install -g vellum@latest
+    else
+        info "Installing vellum globally..."
+        bun install -g vellum@latest
+    fi
+
+    if ! command -v vellum >/dev/null 2>&1; then
+        error "vellum installation failed. Please install manually: bun install -g vellum"
+        exit 1
+    fi
+
+    success "vellum installed ($(vellum --version 2>/dev/null || echo 'unknown'))"
+}
+
 main() {
     printf "\n"
     printf '  %bVellum Installer%b\n' "$BOLD" "$RESET"
@@ -86,13 +103,14 @@ main() {
 
     ensure_git
     ensure_bun
+    install_vellum
 
     info "Running vellum hatch..."
     printf "\n"
     if [ -n "${VELLUM_SSH_USER:-}" ] && [ "$(id -u)" = "0" ]; then
-        su - "$VELLUM_SSH_USER" -c "set -a; [ -f \"\$HOME/.vellum/.env\" ] && . \"\$HOME/.vellum/.env\"; set +a; export PATH=\"$HOME/.bun/bin:\$PATH\"; bunx vellum hatch"
+        su - "$VELLUM_SSH_USER" -c "set -a; [ -f \"\$HOME/.vellum/.env\" ] && . \"\$HOME/.vellum/.env\"; set +a; export PATH=\"$HOME/.bun/bin:\$PATH\"; vellum hatch"
     else
-        bunx vellum hatch
+        vellum hatch
     fi
 }
 

package/src/commands/hatch.ts

@@ -1,8 +1,8 @@
 import { spawn } from "child_process";
 import { randomBytes } from "crypto";
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
 import { createRequire } from "module";
-import { tmpdir, userInfo } from "os";
+import { tmpdir, userInfo, homedir } from "os";
 import { dirname, join } from "path";
 
 import { buildOpenclawStartupScript } from "../adapters/openclaw";
@@ -26,8 +26,18 @@ import { exec, execOutput } from "../lib/step-runner";
 const _require = createRequire(import.meta.url);
 
 const INSTALL_SCRIPT_REMOTE_PATH = "/tmp/vellum-install.sh";
-const INSTALL_SCRIPT_PATH = join(import.meta.dir, "..", "adapters", "install.sh");
 const MACHINE_TYPE = "e2-standard-4"; // 4 vCPUs, 16 GB memory
+
+// Resolve the install script path. In source tree, use the file directly.
+// In compiled binary ($bunfs), the file may not be available.
+async function resolveInstallScriptPath(): Promise<string | null> {
+  const sourcePath = join(import.meta.dir, "..", "adapters", "install.sh");
+  if (existsSync(sourcePath)) {
+    return sourcePath;
+  }
+  console.warn("⚠️  Install script not found at", sourcePath, "(expected in compiled binary)");
+  return null;
+}
 const HATCH_TIMEOUT_MS: Record<Species, number> = {
   vellum: 2 * 60 * 1000,
   openclaw: 10 * 60 * 1000,
@@ -85,6 +95,7 @@ export async function buildStartupScript(
   sshUser: string,
   anthropicApiKey: string,
   instanceName: string,
+  cloud: RemoteHost,
 ): Promise<string> {
   const platformUrl = process.env.VELLUM_ASSISTANT_PLATFORM_URL ?? "https://assistant.vellum.ai";
   const timestampRedirect = buildTimestampRedirect();
@@ -102,7 +113,7 @@ export async function buildStartupScript(
     );
   }
 
-  const interfacesSeed = buildInterfacesSeed();
+  const interfacesSeed = await buildInterfacesSeed();
 
   return `#!/bin/bash
 set -e
@@ -115,6 +126,7 @@ ANTHROPIC_API_KEY=${anthropicApiKey}
 GATEWAY_RUNTIME_PROXY_ENABLED=true
 RUNTIME_PROXY_BEARER_TOKEN=${bearerToken}
 VELLUM_ASSISTANT_NAME=${instanceName}
+VELLUM_CLOUD=${cloud}
 ${interfacesSeed}
 mkdir -p "\$HOME/.vellum"
 cat > "\$HOME/.vellum/.env" << DOTENV_EOF
@@ -123,6 +135,7 @@ GATEWAY_RUNTIME_PROXY_ENABLED=\$GATEWAY_RUNTIME_PROXY_ENABLED
 RUNTIME_PROXY_BEARER_TOKEN=\$RUNTIME_PROXY_BEARER_TOKEN
 INTERFACES_SEED_DIR=\$INTERFACES_SEED_DIR
 RUNTIME_HTTP_PORT=7821
+VELLUM_CLOUD=\$VELLUM_CLOUD
 DOTENV_EOF
 
 mkdir -p "\$HOME/.vellum/workspace"
@@ -154,6 +167,7 @@ interface HatchArgs {
   detached: boolean;
   name: string | null;
   remote: RemoteHost;
+  daemonOnly: boolean;
 }
 
 function parseArgs(): HatchArgs {
@@ -162,11 +176,14 @@ function parseArgs(): HatchArgs {
   let detached = false;
   let name: string | null = null;
   let remote: RemoteHost = DEFAULT_REMOTE;
+  let daemonOnly = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "-d") {
       detached = true;
+    } else if (arg === "--daemon-only") {
+      daemonOnly = true;
     } else if (arg === "--name") {
       const next = args[i + 1];
       if (!next || next.startsWith("-")) {
@@ -189,13 +206,13 @@ function parseArgs(): HatchArgs {
       species = arg as Species;
     } else {
       console.error(
-        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>`,
+        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --daemon-only, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>`,
       );
       process.exit(1);
     }
   }
 
-  return { species, detached, name, remote };
+  return { species, detached, name, remote, daemonOnly };
 }
 
 export interface PollResult {
@@ -304,14 +321,16 @@ async function recoverFromCurlFailure(
   sshUser: string,
   account?: string,
 ): Promise<void> {
-  if (!existsSync(INSTALL_SCRIPT_PATH)) {
-    throw new Error(`Install script not found at ${INSTALL_SCRIPT_PATH}`);
+  const installScriptPath = await resolveInstallScriptPath();
+  if (!installScriptPath) {
+    console.warn("⚠️  Skipping install script upload (not available in compiled binary)");
+    return;
   }
 
   const scpArgs = [
     "compute",
     "scp",
-    INSTALL_SCRIPT_PATH,
+    installScriptPath,
     `${instanceName}:${INSTALL_SCRIPT_REMOTE_PATH}`,
     `--zone=${zone}`,
     `--project=${project}`,
@@ -511,6 +530,7 @@ async function hatchGcp(
       sshUser,
       anthropicApiKey,
       instanceName,
+      "gcp",
     );
     const startupScriptPath = join(tmpdir(), `${instanceName}-startup.sh`);
     writeFileSync(startupScriptPath, startupScript);
@@ -689,19 +709,25 @@ async function hatchCustom(
       sshUser,
       anthropicApiKey,
       instanceName,
+      "custom",
     );
     const startupScriptPath = join(tmpdir(), `${instanceName}-startup.sh`);
     writeFileSync(startupScriptPath, startupScript);
 
     try {
-      console.log("📋 Uploading install script to instance...");
-      await exec("scp", [
-        "-o", "StrictHostKeyChecking=no",
-        "-o", "UserKnownHostsFile=/dev/null",
-        "-o", "LogLevel=ERROR",
-        INSTALL_SCRIPT_PATH,
-        `${host}:${INSTALL_SCRIPT_REMOTE_PATH}`,
-      ]);
+      const installScriptPath = await resolveInstallScriptPath();
+      if (installScriptPath) {
+        console.log("📋 Uploading install script to instance...");
+        await exec("scp", [
+          "-o", "StrictHostKeyChecking=no",
+          "-o", "UserKnownHostsFile=/dev/null",
+          "-o", "LogLevel=ERROR",
+          installScriptPath,
+          `${host}:${INSTALL_SCRIPT_REMOTE_PATH}`,
+        ]);
+      } else {
+        console.warn("⚠️  Skipping install script upload (not available in compiled binary)");
+      }
 
       console.log("📋 Uploading startup script to instance...");
       const remoteStartupPath = `/tmp/${instanceName}-startup.sh`;
@@ -754,57 +780,229 @@ async function hatchCustom(
   }
 }
 
+function isGatewaySourceDir(dir: string): boolean {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath) || !existsSync(join(dir, "src", "index.ts"))) return false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    return pkg.name === "@vellumai/vellum-gateway";
+  } catch {
+    return false;
+  }
+}
+
+function findGatewaySourceFromCwd(): string | undefined {
+  let current = process.cwd();
+  while (true) {
+    if (isGatewaySourceDir(current)) {
+      return current;
+    }
+    const nestedCandidate = join(current, "gateway");
+    if (isGatewaySourceDir(nestedCandidate)) {
+      return nestedCandidate;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return undefined;
+    }
+    current = parent;
+  }
+}
+
 function resolveGatewayDir(): string {
+  const override = process.env.VELLUM_GATEWAY_DIR?.trim();
+  if (override) {
+    if (!isGatewaySourceDir(override)) {
+      throw new Error(
+        `VELLUM_GATEWAY_DIR is set to "${override}", but it is not a valid gateway source directory.`,
+      );
+    }
+    return override;
+  }
+
   const sourceDir = join(import.meta.dir, "..", "..", "..", "gateway");
-  if (existsSync(sourceDir)) {
+  if (isGatewaySourceDir(sourceDir)) {
     return sourceDir;
   }
 
+  const cwdSourceDir = findGatewaySourceFromCwd();
+  if (cwdSourceDir) {
+    return cwdSourceDir;
+  }
+
   try {
     const pkgPath = _require.resolve("@vellumai/vellum-gateway/package.json");
     return dirname(pkgPath);
   } catch {
     throw new Error(
-      "Gateway not found. Ensure @vellumai/vellum-gateway is installed or run from the source tree.",
+      "Gateway not found. Ensure @vellumai/vellum-gateway is installed, run from the source tree, or set VELLUM_GATEWAY_DIR.",
     );
   }
 }
 
-async function hatchLocal(species: Species, name: string | null): Promise<void> {
-  const instanceName =
-    name ?? process.env.VELLUM_ASSISTANT_NAME ?? `${species}-${generateRandomSuffix()}`;
+function normalizeIngressUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().replace(/\/+$/, "");
+  return normalized || undefined;
+}
 
-  console.log(`🥚 Hatching local assistant: ${instanceName}`);
-  console.log(`   Species: ${species}`);
-  console.log("");
+function readWorkspaceIngressPublicBaseUrl(): string | undefined {
+  const baseDataDir = process.env.BASE_DATA_DIR?.trim() || (process.env.HOME ?? homedir());
+  const workspaceConfigPath = join(baseDataDir, ".vellum", "workspace", "config.json");
+  try {
+    const raw = JSON.parse(readFileSync(workspaceConfigPath, "utf-8")) as Record<string, unknown>;
+    const ingress = raw.ingress as Record<string, unknown> | undefined;
+    return normalizeIngressUrl(ingress?.publicBaseUrl);
+  } catch {
+    return undefined;
+  }
+}
 
-  console.log("🔨 Starting local daemon...");
+async function discoverPublicUrl(): Promise<string | undefined> {
+  const cloud = process.env.VELLUM_CLOUD;
+  if (!cloud || cloud === "local") {
+    return `http://localhost:${GATEWAY_PORT}`;
+  }
 
+  let externalIp: string | undefined;
+  try {
+    if (cloud === "gcp") {
+      const resp = await fetch(
+        "http://169.254.169.254/computeMetadata/v1/instance/network-interfaces/0/access-configs/0/external-ip",
+        { headers: { "Metadata-Flavor": "Google" } },
+      );
+      if (resp.ok) externalIp = (await resp.text()).trim();
+    } else if (cloud === "aws") {
+      // Use IMDSv2 (token-based) for compatibility with HttpTokens=required
+      const tokenResp = await fetch(
+        "http://169.254.169.254/latest/api/token",
+        { method: "PUT", headers: { "X-aws-ec2-metadata-token-ttl-seconds": "30" } },
+      );
+      if (tokenResp.ok) {
+        const token = await tokenResp.text();
+        const ipResp = await fetch(
+          "http://169.254.169.254/latest/meta-data/public-ipv4",
+          { headers: { "X-aws-ec2-metadata-token": token } },
+        );
+        if (ipResp.ok) externalIp = (await ipResp.text()).trim();
+      }
+    }
+  } catch {
+    // metadata service not reachable
+  }
+
+  if (externalIp) {
+    console.log(`   Discovered external IP: ${externalIp}`);
+    return `http://${externalIp}:${GATEWAY_PORT}`;
+  }
+  return undefined;
+}
+
+export async function startLocalDaemon(): Promise<void> {
   if (process.env.VELLUM_DESKTOP_APP) {
+    // When running inside the desktop app, the CLI owns the daemon lifecycle.
+    // Find the vellum-daemon binary adjacent to the CLI binary.
     const daemonBinary = join(dirname(process.execPath), "vellum-daemon");
-    const child = spawn(daemonBinary, [], {
-      detached: true,
-      stdio: "ignore",
-      env: { ...process.env },
-    });
-    child.unref();
-
-    const homeDir = process.env.HOME ?? userInfo().homedir;
-    const socketPath = join(homeDir, ".vellum", "vellum.sock");
-    const maxWait = 10000;
-    const pollInterval = 100;
-    let waited = 0;
-    while (waited < maxWait) {
-      if (existsSync(socketPath)) {
-        break;
+    if (!existsSync(daemonBinary)) {
+      throw new Error(
+        `vellum-daemon binary not found at ${daemonBinary}.\n` +
+          "  Ensure the daemon binary is bundled alongside the CLI in the app bundle.",
+      );
+    }
+
+    const vellumDir = join(homedir(), ".vellum");
+    const pidFile = join(vellumDir, "vellum.pid");
+    const socketFile = join(vellumDir, "vellum.sock");
+
+    // If a daemon is already running, skip spawning a new one.
+    // This prevents cascading kill→restart cycles when multiple callers
+    // invoke hatch() concurrently (setupDaemonClient + ensureDaemonConnected).
+    let daemonAlive = false;
+    if (existsSync(pidFile)) {
+      try {
+        const pid = parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
+        if (!isNaN(pid)) {
+          try {
+            process.kill(pid, 0); // Check if alive
+            daemonAlive = true;
+            console.log(`   Daemon already running (pid ${pid})\n`);
+          } catch {
+            // Process doesn't exist, clean up stale PID file
+            try { unlinkSync(pidFile); } catch {}
+          }
+        }
+      } catch {}
+    }
+
+    if (!daemonAlive) {
+      // Remove stale socket so we can detect the fresh one
+      try { unlinkSync(socketFile); } catch {}
+
+      console.log("🔨 Starting daemon...");
+
+      // Ensure ~/.vellum/ exists for PID/socket files
+      mkdirSync(vellumDir, { recursive: true });
+
+      // Build a minimal environment for the daemon. When launched from the
+      // macOS app the CLI inherits a huge environment (XPC_SERVICE_NAME,
+      // __CFBundleIdentifier, CLAUDE_CODE_ENTRYPOINT, etc.) that can cause
+      // the daemon to take 50+ seconds to start instead of ~1s.
+      const daemonEnv: Record<string, string> = {
+        HOME: process.env.HOME || homedir(),
+        PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
+        VELLUM_DAEMON_TCP_ENABLED: "1",
+      };
+      // Forward optional config env vars the daemon may need
+      for (const key of [
+        "ANTHROPIC_API_KEY",
+        "BASE_DATA_DIR",
+        "VELLUM_DAEMON_TCP_PORT",
+        "VELLUM_DAEMON_TCP_HOST",
+        "VELLUM_DAEMON_SOCKET",
+        "VELLUM_DEBUG",
+        "SENTRY_DSN",
+        "TMPDIR",
+        "USER",
+        "LANG",
+      ]) {
+        if (process.env[key]) {
+          daemonEnv[key] = process.env[key]!;
+        }
+      }
+
+      const child = spawn(daemonBinary, [], {
+        detached: true,
+        stdio: "ignore",
+        env: daemonEnv,
+      });
+      child.unref();
+
+      // Write PID file immediately so the health monitor can find the process
+      // and concurrent hatch() calls see it as alive.
+      if (child.pid) {
+        writeFileSync(pidFile, String(child.pid), "utf-8");
       }
-      await new Promise((r) => setTimeout(r, pollInterval));
-      waited += pollInterval;
     }
-    if (!existsSync(socketPath)) {
-      console.warn("⚠️  Daemon socket did not appear within 10s — continuing anyway");
+
+    // Wait for socket at ~/.vellum/vellum.sock (up to 15s)
+    if (!existsSync(socketFile)) {
+      const maxWait = 15000;
+      const start = Date.now();
+      while (Date.now() - start < maxWait) {
+        if (existsSync(socketFile)) {
+          break;
+        }
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    }
+    if (existsSync(socketFile)) {
+      console.log("   Daemon socket ready\n");
+    } else {
+      console.log("   ⚠️  Daemon socket did not appear within 15s — continuing anyway\n");
     }
   } else {
+    console.log("🔨 Starting local daemon...");
+
     // Source tree layout: cli/src/commands/ -> ../../.. -> repo root -> assistant/src/index.ts
     const sourceTreeIndex = join(import.meta.dir, "..", "..", "..", "assistant", "src", "index.ts");
     // bunx layout: @vellumai/cli/src/commands/ -> ../../../.. -> node_modules/ -> vellum/src/index.ts
@@ -847,45 +1045,93 @@ async function hatchLocal(species: Species, name: string | null): Promise<void>
       child.on("error", reject);
     });
   }
+}
+
+export async function startGateway(): Promise<string> {
+  const publicUrl = await discoverPublicUrl();
+  if (publicUrl) {
+    console.log(`   Public URL: ${publicUrl}`);
+  }
 
   console.log("🌐 Starting gateway...");
   const gatewayDir = resolveGatewayDir();
+  const gatewayEnv: Record<string, string> = {
+    ...process.env as Record<string, string>,
+    GATEWAY_RUNTIME_PROXY_ENABLED: "true",
+    GATEWAY_RUNTIME_PROXY_REQUIRE_AUTH: "false",
+  };
+  const workspaceIngressPublicBaseUrl = readWorkspaceIngressPublicBaseUrl();
+  const ingressPublicBaseUrl =
+    workspaceIngressPublicBaseUrl
+    ?? normalizeIngressUrl(process.env.INGRESS_PUBLIC_BASE_URL);
+  if (ingressPublicBaseUrl) {
+    gatewayEnv.INGRESS_PUBLIC_BASE_URL = ingressPublicBaseUrl;
+    console.log(`   Ingress URL: ${ingressPublicBaseUrl}`);
+    if (!workspaceIngressPublicBaseUrl) {
+      console.log("   (using INGRESS_PUBLIC_BASE_URL env fallback)");
+    }
+  }
+  if (publicUrl) gatewayEnv.GATEWAY_PUBLIC_URL = publicUrl;
+
   const gateway = spawn("bun", ["run", "src/index.ts"], {
     cwd: gatewayDir,
     detached: true,
     stdio: "ignore",
-    env: {
-      ...process.env,
-      GATEWAY_RUNTIME_PROXY_ENABLED: "true",
-      GATEWAY_RUNTIME_PROXY_REQUIRE_AUTH: "false",
-    },
+    env: gatewayEnv,
   });
   gateway.unref();
   console.log("✅ Gateway started\n");
+  return publicUrl || `http://localhost:${GATEWAY_PORT}`;
+}
+
+async function hatchLocal(species: Species, name: string | null, daemonOnly: boolean = false): Promise<void> {
+  const instanceName =
+    name ?? process.env.VELLUM_ASSISTANT_NAME ?? `${species}-${generateRandomSuffix()}`;
+
+  console.log(`🥚 Hatching local assistant: ${instanceName}`);
+  console.log(`   Species: ${species}`);
+  console.log("");
+
+  await startLocalDaemon();
+
+  // The desktop app communicates with the daemon directly via Unix socket,
+  // so the HTTP gateway is only needed for non-desktop (CLI) usage.
+  let runtimeUrl: string;
+
+  if (process.env.VELLUM_DESKTOP_APP) {
+    // No gateway needed — the macOS app uses DaemonClient over the Unix socket.
+    runtimeUrl = "local";
+  } else {
+    runtimeUrl = await startGateway();
+  }
 
-  const runtimeUrl = `http://localhost:${GATEWAY_PORT}`;
+  const baseDataDir = join(process.env.BASE_DATA_DIR?.trim() || (process.env.HOME ?? userInfo().homedir), ".vellum");
   const localEntry: AssistantEntry = {
     assistantId: instanceName,
     runtimeUrl,
+    baseDataDir,
     cloud: "local",
     species,
     hatchedAt: new Date().toISOString(),
   };
-  saveAssistantEntry(localEntry);
+  if (!daemonOnly) {
+    saveAssistantEntry(localEntry);
 
-  console.log("");
-  console.log(`✅ Local assistant hatched!`);
-  console.log("");
-  console.log("Instance details:");
-  console.log(`  Name: ${instanceName}`);
-  console.log(`  Runtime: ${runtimeUrl}`);
-  console.log("");
+    console.log("");
+    console.log(`✅ Local assistant hatched!`);
+    console.log("");
+    console.log("Instance details:");
+    console.log(`  Name: ${instanceName}`);
+    console.log(`  Runtime: ${runtimeUrl}`);
+    console.log("");
+  }
 }
 
 function getCliVersion(): string {
   try {
-    const pkgPath = join(import.meta.dir, "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    // Use createRequire for JSON import — works in both Bun dev and compiled binary.
+    const require = createRequire(import.meta.url);
+    const pkg = require("../../package.json") as { version?: string };
     return pkg.version ?? "unknown";
   } catch {
     return "unknown";
@@ -896,10 +1142,10 @@ export async function hatch(): Promise<void> {
   const cliVersion = getCliVersion();
   console.log(`@vellumai/cli v${cliVersion}`);
 
-  const { species, detached, name, remote } = parseArgs();
+  const { species, detached, name, remote, daemonOnly } = parseArgs();
 
   if (remote === "local") {
-    await hatchLocal(species, name);
+    await hatchLocal(species, name, daemonOnly);
     return;
   }
 

package/src/commands/ps.ts

@@ -0,0 +1,92 @@
+import { loadAllAssistants } from "../lib/assistant-config";
+import { checkHealth } from "../lib/health-check";
+import { withStatusEmoji } from "../lib/status-emoji";
+
+interface TableRow {
+  name: string;
+  status: string;
+  info: string;
+}
+
+interface ColWidths {
+  name: number;
+  status: number;
+  info: number;
+}
+
+function pad(s: string, w: number): string {
+  return s + " ".repeat(Math.max(0, w - s.length));
+}
+
+function computeColWidths(rows: TableRow[]): ColWidths {
+  const headers: TableRow = { name: "NAME", status: "STATUS", info: "INFO" };
+  const all = [headers, ...rows];
+  return {
+    name: Math.max(...all.map((r) => r.name.length)),
+    status: Math.max(...all.map((r) => r.status.length), "checking...".length),
+    info: Math.max(...all.map((r) => r.info.length)),
+  };
+}
+
+function formatRow(r: TableRow, colWidths: ColWidths): string {
+  return `  ${pad(r.name, colWidths.name)}  ${pad(r.status, colWidths.status)}  ${r.info}`;
+}
+
+export async function ps(): Promise<void> {
+  const assistants = loadAllAssistants();
+
+  if (assistants.length === 0) {
+    console.log("No assistants found.");
+    return;
+  }
+
+  const rows: TableRow[] = assistants.map((a) => {
+    const infoParts = [a.runtimeUrl];
+    if (a.cloud) infoParts.push(`cloud: ${a.cloud}`);
+    if (a.species) infoParts.push(`species: ${a.species}`);
+
+    return {
+      name: a.assistantId,
+      status: withStatusEmoji("checking..."),
+      info: infoParts.join(" | "),
+    };
+  });
+
+  const colWidths = computeColWidths(rows);
+
+  const headers: TableRow = { name: "NAME", status: "STATUS", info: "INFO" };
+  console.log(formatRow(headers, colWidths));
+  const sep = `  ${"-".repeat(colWidths.name)}  ${"-".repeat(colWidths.status)}  ${"-".repeat(colWidths.info)}`;
+  console.log(sep);
+  for (const row of rows) {
+    console.log(formatRow(row, colWidths));
+  }
+
+  const totalDataRows = rows.length;
+
+  await Promise.all(
+    assistants.map(async (a, rowIndex) => {
+      const health = await checkHealth(a.runtimeUrl);
+
+      const infoParts = [a.runtimeUrl];
+      if (a.cloud) infoParts.push(`cloud: ${a.cloud}`);
+      if (a.species) infoParts.push(`species: ${a.species}`);
+      if (health.detail) infoParts.push(health.detail);
+
+      const updatedRow: TableRow = {
+        name: a.assistantId,
+        status: withStatusEmoji(health.status),
+        info: infoParts.join(" | "),
+      };
+
+      const linesUp = totalDataRows - rowIndex;
+      process.stdout.write(
+        `\x1b[${linesUp}A` +
+          `\r\x1b[K` +
+          formatRow(updatedRow, colWidths) +
+          `\n` +
+          (linesUp > 1 ? `\x1b[${linesUp - 1}B` : ""),
+      );
+    }),
+  );
+}

package/src/commands/retire.ts

@@ -1,5 +1,5 @@
 import { spawn } from "child_process";
-import { rmSync } from "fs";
+import { existsSync, readFileSync, rmSync, unlinkSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 
@@ -34,30 +34,68 @@ function extractHostFromUrl(url: string): string {
 async function retireLocal(): Promise<void> {
   console.log("\u{1F5D1}\ufe0f  Stopping local daemon...\n");
 
-  try {
-    const child = spawn("bunx", ["vellum", "daemon", "stop"], {
-      stdio: "inherit",
-    });
-
-    await new Promise<void>((resolve) => {
-      child.on("close", () => resolve());
-      child.on("error", () => resolve());
-    });
-  } catch {}
-
-  try {
-    const killGateway = spawn("pkill", ["-f", "gateway/src/index.ts"], {
-      stdio: "ignore",
-    });
+  const vellumDir = join(homedir(), ".vellum");
+  const isDesktopApp = !!process.env.VELLUM_DESKTOP_APP;
+
+  // Stop daemon via PID file (works for both desktop app and standalone)
+  const pidFile = join(vellumDir, "vellum.pid");
+  const socketFile = join(vellumDir, "vellum.sock");
+
+  if (existsSync(pidFile)) {
+    try {
+      const pid = parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
+      if (!isNaN(pid)) {
+        try {
+          process.kill(pid, 0); // Check if alive
+          process.kill(pid, "SIGTERM");
+          const deadline = Date.now() + 2000;
+          while (Date.now() < deadline) {
+            try {
+              process.kill(pid, 0);
+              await new Promise((r) => setTimeout(r, 100));
+            } catch {
+              break;
+            }
+          }
+          try {
+            process.kill(pid, 0);
+            process.kill(pid, "SIGKILL");
+          } catch {}
+        } catch {}
+      }
+    } catch {}
+    try { unlinkSync(pidFile); } catch {}
+    try { unlinkSync(socketFile); } catch {}
+  }
 
-    await new Promise<void>((resolve) => {
-      killGateway.on("close", () => resolve());
-      killGateway.on("error", () => resolve());
-    });
-  } catch {}
+  if (!isDesktopApp) {
+    // Non-desktop: also stop daemon via bunx (fallback) and kill gateway
+    try {
+      const child = spawn("bunx", ["vellum", "daemon", "stop"], {
+        stdio: "inherit",
+      });
+
+      await new Promise<void>((resolve) => {
+        child.on("close", () => resolve());
+        child.on("error", () => resolve());
+      });
+    } catch {}
+
+    try {
+      const killGateway = spawn("pkill", ["-f", "gateway/src/index.ts"], {
+        stdio: "ignore",
+      });
+
+      await new Promise<void>((resolve) => {
+        killGateway.on("close", () => resolve());
+        killGateway.on("error", () => resolve());
+      });
+    } catch {}
+
+    // Only delete ~/.vellum in non-desktop mode
+    rmSync(vellumDir, { recursive: true, force: true });
+  }
 
-  const vellumDir = join(homedir(), ".vellum");
-  rmSync(vellumDir, { recursive: true, force: true });
   console.log("\u2705 Local instance retired.");
 }
 

package/src/commands/sleep.ts

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync, unlinkSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+export async function sleep(): Promise<void> {
+  const vellumDir = join(homedir(), ".vellum");
+  const pidFile = join(vellumDir, "vellum.pid");
+  const socketFile = join(vellumDir, "vellum.sock");
+
+  if (!existsSync(pidFile)) {
+    console.log("No daemon PID file found — nothing to stop.");
+    process.exit(0);
+  }
+
+  const pidStr = readFileSync(pidFile, "utf-8").trim();
+  const pid = parseInt(pidStr, 10);
+
+  if (isNaN(pid)) {
+    console.log("Invalid PID file contents — cleaning up.");
+    try { unlinkSync(pidFile); } catch {}
+    try { unlinkSync(socketFile); } catch {}
+    process.exit(0);
+  }
+
+  // Check if process is alive
+  try {
+    process.kill(pid, 0);
+  } catch {
+    console.log(`Daemon process ${pid} is not running — cleaning up stale files.`);
+    try { unlinkSync(pidFile); } catch {}
+    try { unlinkSync(socketFile); } catch {}
+    process.exit(0);
+  }
+
+  console.log(`Stopping daemon (pid ${pid})...`);
+  process.kill(pid, "SIGTERM");
+
+  // Wait up to 2s for graceful exit
+  const deadline = Date.now() + 2000;
+  while (Date.now() < deadline) {
+    try {
+      process.kill(pid, 0);
+      await new Promise((r) => setTimeout(r, 100));
+    } catch {
+      break; // Process exited
+    }
+  }
+
+  // Force kill if still alive
+  try {
+    process.kill(pid, 0);
+    console.log("Daemon did not exit after SIGTERM, sending SIGKILL...");
+    process.kill(pid, "SIGKILL");
+  } catch {
+    // Already dead
+  }
+
+  // Clean up PID and socket files
+  try { unlinkSync(pidFile); } catch {}
+  try { unlinkSync(socketFile); } catch {}
+
+  console.log("Daemon stopped.");
+}

package/src/commands/wake.ts

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+import { startLocalDaemon, startGateway } from "./hatch";
+
+export async function wake(): Promise<void> {
+  const vellumDir = join(homedir(), ".vellum");
+  const pidFile = join(vellumDir, "vellum.pid");
+
+  // Check if daemon is already running
+  let daemonRunning = false;
+  if (existsSync(pidFile)) {
+    const pidStr = readFileSync(pidFile, "utf-8").trim();
+    const pid = parseInt(pidStr, 10);
+    if (!isNaN(pid)) {
+      try {
+        process.kill(pid, 0);
+        daemonRunning = true;
+        console.log(`Daemon already running (pid ${pid}).`);
+      } catch {
+        // Process not alive, will start below
+      }
+    }
+  }
+
+  if (!daemonRunning) {
+    await startLocalDaemon();
+  }
+
+  // Start gateway (non-desktop only)
+  if (!process.env.VELLUM_DESKTOP_APP) {
+    await startGateway();
+  }
+
+  console.log("✅ Wake complete.");
+}

package/src/index.ts

@@ -1,11 +1,17 @@
 #!/usr/bin/env bun
 
 import { hatch } from "./commands/hatch";
+import { ps } from "./commands/ps";
 import { retire } from "./commands/retire";
+import { sleep } from "./commands/sleep";
+import { wake } from "./commands/wake";
 
 const commands = {
   hatch,
+  ps,
   retire,
+  sleep,
+  wake,
 } as const;
 
 type CommandName = keyof typeof commands;
@@ -19,7 +25,10 @@ async function main() {
     console.log("");
     console.log("Commands:");
     console.log("  hatch    Create a new assistant instance");
+    console.log("  ps       List assistants and their health status");
     console.log("  retire   Delete an assistant instance");
+    console.log("  sleep    Stop the daemon process");
+    console.log("  wake     Start the daemon and gateway");
     process.exit(0);
   }
 

package/src/lib/assistant-config.ts

@@ -5,6 +5,7 @@ import { join } from "path";
 export interface AssistantEntry {
   assistantId: string;
   runtimeUrl: string;
+  baseDataDir?: string;
   bearerToken?: string;
   cloud: string;
   instanceId?: string;
@@ -88,6 +89,10 @@ export function removeAssistantEntry(assistantId: string): void {
   writeAssistants(entries.filter((e) => e.assistantId !== assistantId));
 }
 
+export function loadAllAssistants(): AssistantEntry[] {
+  return readAssistants();
+}
+
 export function saveAssistantEntry(entry: AssistantEntry): void {
   const entries = readAssistants();
   entries.unshift(entry);

package/src/lib/aws.ts

@@ -426,6 +426,7 @@ export async function hatchAws(
       sshUser,
       anthropicApiKey,
       instanceName,
+      "aws",
     );
     const startupScriptPath = join(tmpdir(), `${instanceName}-startup.sh`);
     writeFileSync(startupScriptPath, startupScript);
@@ -555,11 +556,29 @@ async function getInstanceIdByName(
   }
 }
 
+async function checkAwsCliAvailable(): Promise<boolean> {
+  try {
+    await execOutput("aws", ["--version"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function retireInstance(
   name: string,
   region: string,
   source?: string,
 ): Promise<void> {
+  const awsOk = await checkAwsCliAvailable();
+  if (!awsOk) {
+    throw new Error(
+      `Cannot retire AWS instance '${name}': AWS CLI is not installed or not in PATH. ` +
+        `Please install the AWS CLI and try again, or terminate the instance manually ` +
+        `via the AWS Console (region=${region}).`,
+    );
+  }
+
   const instanceId = await getInstanceIdByName(name, region);
   if (!instanceId) {
     console.warn(

package/src/lib/gcp.ts

@@ -313,12 +313,30 @@ export async function fetchAndDisplayStartupLogs(
   }
 }
 
+async function checkGcloudAvailable(): Promise<boolean> {
+  try {
+    await execOutput("gcloud", ["--version"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function retireInstance(
   name: string,
   project: string,
   zone: string,
   source?: string,
 ): Promise<void> {
+  const gcloudOk = await checkGcloudAvailable();
+  if (!gcloudOk) {
+    throw new Error(
+      `Cannot retire GCP instance '${name}': gcloud CLI is not installed or not in PATH. ` +
+        `Please install the Google Cloud SDK and try again, or delete the instance manually ` +
+        `via the GCP Console (project=${project}, zone=${zone}).`,
+    );
+  }
+
   const exists = await instanceExists(name, project, zone);
   if (!exists) {
     console.warn(
@@ -354,6 +372,7 @@ export async function retireInstance(
       name,
       `--project=${project}`,
       `--zone=${zone}`,
+      "--quiet",
     ],
     { stdio: "inherit" },
   );

package/src/lib/interfaces-seed.ts

@@ -1,21 +1,28 @@
-import { join } from "path";
+// Read source files using Bun.file() with string concatenation (not join())
+// so Bun's bundler can statically analyze the paths and embed the files
+// in the compiled binary ($bunfs). Files must also be passed via --embed
+// in the bun build --compile invocation.
 
-const constantsSource = await Bun.file(join(import.meta.dir, "constants.ts")).text();
-const defaultMainScreenSource = await Bun.file(join(import.meta.dir, "..", "components", "DefaultMainScreen.tsx")).text();
-
-function inlineLocalImports(source: string): string {
+function inlineLocalImports(source: string, constantsSource: string): string {
   return source
     .replace(/import\s*\{[^}]*\}\s*from\s*["'][^"']*\/constants["'];?\s*\n/, constantsSource + "\n")
     .replace(/import\s*\{[^}]*\}\s*from\s*["']path["'];?\s*\n/, "");
 }
 
-export function buildInterfacesSeed(): string {
-  const mainWindowSource = inlineLocalImports(defaultMainScreenSource);
+export async function buildInterfacesSeed(): Promise<string> {
+  try {
+    const constantsSource = await Bun.file(import.meta.dir + "/constants.ts").text();
+    const defaultMainScreenSource = await Bun.file(import.meta.dir + "/../components/DefaultMainScreen.tsx").text();
+    const mainWindowSource = inlineLocalImports(defaultMainScreenSource, constantsSource);
 
-  return `
+    return `
 INTERFACES_SEED_DIR="/tmp/interfaces-seed"
 mkdir -p "\$INTERFACES_SEED_DIR/tui"
 cat > "\$INTERFACES_SEED_DIR/tui/main-window.tsx" << 'INTERFACES_SEED_EOF'
 ${mainWindowSource}INTERFACES_SEED_EOF
 `;
+  } catch (err) {
+    console.warn("⚠️  Could not embed interfaces seed files (expected in compiled binary without --embed):", (err as Error).message);
+    return "# interfaces-seed: skipped (source files not available in compiled binary)";
+  }
 }

package/src/lib/openclaw-runtime-server.ts

@@ -1,9 +1,13 @@
-import { join } from "path";
+// Read source file using Bun.file() with string concatenation (not join())
+// so Bun's bundler can statically analyze the path and embed the file
+// in the compiled binary ($bunfs). The file must also be passed via --embed
+// in the bun build --compile invocation.
 
 export async function buildOpenclawRuntimeServer(): Promise<string> {
-  const serverSource = await Bun.file(join(import.meta.dir, "..", "adapters", "openclaw-http-server.ts")).text();
+  try {
+    const serverSource = await Bun.file(import.meta.dir + "/../adapters/openclaw-http-server.ts").text();
 
-  return `
+    return `
 cat > /opt/openclaw-runtime-server.ts << 'RUNTIME_SERVER_EOF'
 ${serverSource}
 RUNTIME_SERVER_EOF
@@ -12,4 +16,8 @@ mkdir -p "\$HOME/.vellum"
 nohup bun run /opt/openclaw-runtime-server.ts >> "\$HOME/.vellum/http-gateway.log" 2>&1 &
 echo "OpenClaw runtime server started (PID: \$!)"
 `;
+  } catch (err) {
+    console.warn("⚠️  Could not embed openclaw runtime server (expected in compiled binary without --embed):", (err as Error).message);
+    return "# openclaw-runtime-server: skipped (source files not available in compiled binary)";
+  }
 }

package/scripts/bump.ts

@@ -1,36 +0,0 @@
-import { resolve } from "path";
-
-const CLI_DIR = resolve(import.meta.dirname, "..");
-const ASSISTANT_DIR = resolve(CLI_DIR, "../assistant");
-
-const cliPkgPath = resolve(CLI_DIR, "package.json");
-const assistantPkgPath = resolve(ASSISTANT_DIR, "package.json");
-const assistantLockPath = resolve(ASSISTANT_DIR, "bun.lock");
-
-function bumpPatch(version: string): string {
-  const parts = version.split(".");
-  parts[2] = String(Number(parts[2]) + 1);
-  return parts.join(".");
-}
-
-const cliPkg = await Bun.file(cliPkgPath).json();
-const oldVersion: string = cliPkg.version;
-const newVersion = bumpPatch(oldVersion);
-cliPkg.version = newVersion;
-await Bun.write(cliPkgPath, JSON.stringify(cliPkg, null, 2) + "\n");
-
-const assistantPkg = await Bun.file(assistantPkgPath).json();
-assistantPkg.dependencies["@vellumai/cli"] = newVersion;
-assistantPkg.version = bumpPatch(assistantPkg.version);
-await Bun.write(assistantPkgPath, JSON.stringify(assistantPkg, null, 2) + "\n");
-
-let lockContent = await Bun.file(assistantLockPath).text();
-lockContent = lockContent.replace(
-  /"@vellumai\/cli": "[^"]*"/g,
-  `"@vellumai/cli": "${newVersion}"`
-);
-lockContent = lockContent.replace(
-  /@vellumai\/cli@\d+\.\d+\.\d+/g,
-  `@vellumai/cli@${newVersion}`
-);
-await Bun.write(assistantLockPath, lockContent);