@vellumai/cli 0.1.7 → 0.1.9

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,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "bin": {

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,
@@ -84,6 +94,8 @@ export async function buildStartupScript(
   bearerToken: string,
   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();
@@ -101,7 +113,7 @@ export async function buildStartupScript(
     );
   }
 
-  const interfacesSeed = buildInterfacesSeed();
+  const interfacesSeed = await buildInterfacesSeed();
 
   return `#!/bin/bash
 set -e
@@ -113,6 +125,8 @@ ${userSetup}
 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
@@ -121,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"
@@ -135,6 +150,7 @@ CONFIG_EOF
 ${ownershipFixup}
 
 export VELLUM_SSH_USER="\$SSH_USER"
+export VELLUM_ASSISTANT_NAME="\$VELLUM_ASSISTANT_NAME"
 echo "Downloading install script from ${platformUrl}/install.sh..."
 curl -fsSL ${platformUrl}/install.sh -o ${INSTALL_SCRIPT_REMOTE_PATH}
 echo "Install script downloaded (\$(wc -c < ${INSTALL_SCRIPT_REMOTE_PATH}) bytes)"
@@ -151,6 +167,7 @@ interface HatchArgs {
   detached: boolean;
   name: string | null;
   remote: RemoteHost;
+  daemonOnly: boolean;
 }
 
 function parseArgs(): HatchArgs {
@@ -159,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("-")) {
@@ -186,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 {
@@ -301,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}`,
@@ -502,7 +524,14 @@ async function hatchGcp(
       console.error("Error: ANTHROPIC_API_KEY environment variable is not set.");
       process.exit(1);
     }
-    const startupScript = await buildStartupScript(species, bearerToken, sshUser, anthropicApiKey);
+    const startupScript = await buildStartupScript(
+      species,
+      bearerToken,
+      sshUser,
+      anthropicApiKey,
+      instanceName,
+      "gcp",
+    );
     const startupScriptPath = join(tmpdir(), `${instanceName}-startup.sh`);
     writeFileSync(startupScriptPath, startupScript);
 
@@ -674,19 +703,31 @@ async function hatchCustom(
       process.exit(1);
     }
 
-    const startupScript = await buildStartupScript(species, bearerToken, sshUser, anthropicApiKey);
+    const startupScript = await buildStartupScript(
+      species,
+      bearerToken,
+      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`;
@@ -739,59 +780,239 @@ async function hatchCustom(
   }
 }
 
+function isGatewaySourceDir(dir: string): boolean {
+  return existsSync(join(dir, "package.json")) && existsSync(join(dir, "src", "index.ts"));
+}
+
+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 ?? `${species}-${generateRandomSuffix()}`;
+function normalizeIngressUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().replace(/\/+$/, "");
+  return normalized || undefined;
+}
+
+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;
+  }
+}
+
+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;
+}
+
+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("");
 
-  console.log("🔨 Starting local daemon...");
-
   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
+    const bunxIndex = join(import.meta.dir, "..", "..", "..", "..", "vellum", "src", "index.ts");
     let assistantIndex = sourceTreeIndex;
 
+    if (!existsSync(assistantIndex)) {
+      assistantIndex = bunxIndex;
+    }
+
     if (!existsSync(assistantIndex)) {
       try {
         const vellumPkgPath = _require.resolve("vellum/package.json");
@@ -825,44 +1046,77 @@ async function hatchLocal(species: Species, name: string | null): Promise<void>
     });
   }
 
-  console.log("🌐 Starting gateway...");
-  const gatewayDir = resolveGatewayDir();
-  const gateway = spawn("bun", ["run", "src/index.ts"], {
-    cwd: gatewayDir,
-    detached: true,
-    stdio: "ignore",
-    env: {
-      ...process.env,
+  // 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 {
+    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",
-    },
-  });
-  gateway.unref();
-  console.log("✅ Gateway started\n");
+    };
+    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 runtimeUrl = `http://localhost:${GATEWAY_PORT}`;
+    const gateway = spawn("bun", ["run", "src/index.ts"], {
+      cwd: gatewayDir,
+      detached: true,
+      stdio: "ignore",
+      env: gatewayEnv,
+    });
+    gateway.unref();
+    console.log("✅ Gateway started\n");
+    runtimeUrl = publicUrl || `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";
@@ -873,10 +1127,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/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/index.ts

@@ -2,10 +2,12 @@
 
 import { hatch } from "./commands/hatch";
 import { retire } from "./commands/retire";
+import { sleep } from "./commands/sleep";
 
 const commands = {
   hatch,
   retire,
+  sleep,
 } as const;
 
 type CommandName = keyof typeof commands;
@@ -20,6 +22,7 @@ async function main() {
     console.log("Commands:");
     console.log("  hatch    Create a new assistant instance");
     console.log("  retire   Delete an assistant instance");
+    console.log("  sleep    Stop the daemon process");
     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;

package/src/lib/aws.ts

@@ -420,7 +420,14 @@ export async function hatchAws(
     console.log("\u{1F50D} Finding latest Debian AMI...");
     const amiId = await getLatestDebianAmi(region);
 
-    const startupScript = await buildStartupScript(species, bearerToken, sshUser, anthropicApiKey);
+    const startupScript = await buildStartupScript(
+      species,
+      bearerToken,
+      sshUser,
+      anthropicApiKey,
+      instanceName,
+      "aws",
+    );
     const startupScriptPath = join(tmpdir(), `${instanceName}-startup.sh`);
     writeFileSync(startupScriptPath, startupScript);
 

package/src/lib/gcp.ts

@@ -354,6 +354,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)";
+  }
 }