@vellumai/cli 0.1.1

package/src/commands/hatch.ts

@@ -0,0 +1,806 @@
+import { spawn } from "child_process";
+import { randomBytes } from "crypto";
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { homedir, tmpdir, userInfo } from "os";
+import { join } from "path";
+
+import { buildOpenclawStartupScript } from "../adapters/openclaw";
+import {
+  FIREWALL_TAG,
+  GATEWAY_PORT,
+  SPECIES_CONFIG,
+  VALID_REMOTE_HOSTS,
+  VALID_SPECIES,
+} from "../lib/constants";
+import type { RemoteHost, Species } from "../lib/constants";
+import type { FirewallRuleSpec } from "../lib/gcp";
+import { getActiveProject, instanceExists, syncFirewallRules } from "../lib/gcp";
+import { buildInterfacesSeed } from "../lib/interfaces-seed";
+import { generateRandomSuffix } from "../lib/random-name";
+import { exec, execOutput } from "../lib/step-runner";
+
+const DEFAULT_ZONE = "us-central1-a";
+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
+const HATCH_TIMEOUT_MS = 2 * 60 * 1000; // 2 minutes
+const DEFAULT_SPECIES: Species = "vellum";
+
+const DESIRED_FIREWALL_RULES: FirewallRuleSpec[] = [
+  {
+    name: "allow-vellum-assistant-gateway",
+    direction: "INGRESS",
+    action: "ALLOW",
+    rules: `tcp:${GATEWAY_PORT}`,
+    sourceRanges: "0.0.0.0/0",
+    targetTags: FIREWALL_TAG,
+    description: `Allow gateway ingress on port ${GATEWAY_PORT} for vellum-assistant instances`,
+  },
+  {
+    name: "allow-vellum-assistant-egress",
+    direction: "EGRESS",
+    action: "ALLOW",
+    rules: "all",
+    destinationRanges: "0.0.0.0/0",
+    targetTags: FIREWALL_TAG,
+    description: "Allow all egress traffic for vellum-assistant instances",
+  },
+];
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+function buildTimestampRedirect(): string {
+  return `exec > >(while IFS= read -r line; do printf '[%s] %s\\n' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$line"; done > /var/log/startup-script.log) 2>&1`;
+}
+
+function buildUserSetup(sshUser: string): string {
+  return `
+SSH_USER="${sshUser}"
+if ! id "$SSH_USER" &>/dev/null; then
+  useradd -m -s /bin/bash "$SSH_USER"
+fi
+SSH_USER_HOME=$(eval echo "~$SSH_USER")
+mkdir -p "$SSH_USER_HOME"
+export HOME="$SSH_USER_HOME"
+`;
+}
+
+function buildOwnershipFixup(): string {
+  return `
+chown -R "$SSH_USER:$SSH_USER" "$SSH_USER_HOME" 2>/dev/null || true
+`;
+}
+
+function buildStartupScript(
+  species: Species,
+  bearerToken: string,
+  sshUser: string,
+  anthropicApiKey: string,
+): string {
+  const timestampRedirect = buildTimestampRedirect();
+  const userSetup = buildUserSetup(sshUser);
+  const ownershipFixup = buildOwnershipFixup();
+
+  if (species === "openclaw") {
+    return buildOpenclawStartupScript(
+      bearerToken,
+      sshUser,
+      anthropicApiKey,
+      timestampRedirect,
+      userSetup,
+      ownershipFixup,
+    );
+  }
+
+  const interfacesSeed = buildInterfacesSeed();
+
+  return `#!/bin/bash
+set -e
+
+${timestampRedirect}
+
+trap 'EXIT_CODE=\$?; if [ \$EXIT_CODE -ne 0 ]; then echo "Startup script failed with exit code \$EXIT_CODE" > /var/log/startup-error; fi' EXIT
+${userSetup}
+ANTHROPIC_API_KEY=${anthropicApiKey}
+GATEWAY_RUNTIME_PROXY_ENABLED=true
+RUNTIME_PROXY_BEARER_TOKEN=${bearerToken}
+${interfacesSeed}
+mkdir -p "\$HOME/.vellum"
+cat > "\$HOME/.vellum/.env" << DOTENV_EOF
+ANTHROPIC_API_KEY=\$ANTHROPIC_API_KEY
+GATEWAY_RUNTIME_PROXY_ENABLED=\$GATEWAY_RUNTIME_PROXY_ENABLED
+RUNTIME_PROXY_BEARER_TOKEN=\$RUNTIME_PROXY_BEARER_TOKEN
+INTERFACES_SEED_DIR=\$INTERFACES_SEED_DIR
+DOTENV_EOF
+
+mkdir -p "\$HOME/.vellum/workspace"
+cat > "\$HOME/.vellum/workspace/config.json" << CONFIG_EOF
+{
+  "logFile": {
+    "dir": "\$HOME/.vellum/workspace/data/logs"
+  }
+}
+CONFIG_EOF
+
+${ownershipFixup}
+
+export VELLUM_SSH_USER="\$SSH_USER"
+curl -fsSL https://assistant.vellum.ai/install.sh -o ${INSTALL_SCRIPT_REMOTE_PATH}
+chmod +x ${INSTALL_SCRIPT_REMOTE_PATH}
+source ${INSTALL_SCRIPT_REMOTE_PATH}
+`;
+}
+
+const DEFAULT_REMOTE: RemoteHost = "local";
+
+interface HatchArgs {
+  species: Species;
+  detached: boolean;
+  name: string | null;
+  remote: RemoteHost;
+}
+
+function parseArgs(): HatchArgs {
+  const args = process.argv.slice(3);
+  let species: Species = DEFAULT_SPECIES;
+  let detached = false;
+  let name: string | null = null;
+  let remote: RemoteHost = DEFAULT_REMOTE;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-d") {
+      detached = true;
+    } else if (arg === "--name") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("-")) {
+        console.error("Error: --name requires a value");
+        process.exit(1);
+      }
+      name = next;
+      i++;
+    } else if (arg === "--remote") {
+      const next = args[i + 1];
+      if (!next || !VALID_REMOTE_HOSTS.includes(next as RemoteHost)) {
+        console.error(
+          `Error: --remote requires one of: ${VALID_REMOTE_HOSTS.join(", ")}`,
+        );
+        process.exit(1);
+      }
+      remote = next as RemoteHost;
+      i++;
+    } else if (VALID_SPECIES.includes(arg as Species)) {
+      species = arg as Species;
+    } else {
+      console.error(
+        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>`,
+      );
+      process.exit(1);
+    }
+  }
+
+  return { species, detached, name, remote };
+}
+
+interface PollResult {
+  lastLine: string | null;
+  done: boolean;
+  failed: boolean;
+}
+
+async function pollInstance(
+  instanceName: string,
+  project: string,
+  zone: string,
+): Promise<PollResult> {
+  try {
+    const remoteCmd =
+      "L=$(tail -1 /var/log/startup-script.log 2>/dev/null || true); " +
+      "S=$(systemctl is-active google-startup-scripts.service 2>/dev/null || true); " +
+      "E=$(cat /var/log/startup-error 2>/dev/null || true); " +
+      'printf "%s\\n===HATCH_SEP===\\n%s\\n===HATCH_ERR===\\n%s" "$L" "$S" "$E"';
+    const output = await execOutput("gcloud", [
+      "compute",
+      "ssh",
+      instanceName,
+      `--project=${project}`,
+      `--zone=${zone}`,
+      "--quiet",
+      "--ssh-flag=-o StrictHostKeyChecking=no",
+      "--ssh-flag=-o UserKnownHostsFile=/dev/null",
+      "--ssh-flag=-o ConnectTimeout=10",
+      "--ssh-flag=-o LogLevel=ERROR",
+      `--command=${remoteCmd}`,
+    ]);
+    const sepIdx = output.indexOf("===HATCH_SEP===");
+    if (sepIdx === -1) {
+      return { lastLine: output.trim() || null, done: false, failed: false };
+    }
+    const errIdx = output.indexOf("===HATCH_ERR===");
+    const lastLine = output.substring(0, sepIdx).trim() || null;
+    const statusEnd = errIdx === -1 ? undefined : errIdx;
+    const status = output.substring(sepIdx + "===HATCH_SEP===".length, statusEnd).trim();
+    const errorContent =
+      errIdx === -1 ? "" : output.substring(errIdx + "===HATCH_ERR===".length).trim();
+    const done = lastLine !== null && status !== "active" && status !== "activating";
+    const failed = errorContent.length > 0 || status === "failed";
+    return { lastLine, done, failed };
+  } catch {
+    return { lastLine: null, done: false, failed: false };
+  }
+}
+
+function formatElapsed(ms: number): string {
+  const secs = Math.floor(ms / 1000);
+  const m = Math.floor(secs / 60);
+  const s = secs % 60;
+  return m > 0 ? `${m}m ${s.toString().padStart(2, "0")}s` : `${s}s`;
+}
+
+function pickMessage(messages: string[], elapsedMs: number): string {
+  const idx = Math.floor(elapsedMs / 15000) % messages.length;
+  return messages[idx];
+}
+
+function getPhaseIcon(hasLogs: boolean, elapsedMs: number, species: Species): string {
+  if (!hasLogs) {
+    return elapsedMs < 30000 ? "🥚" : "🪺";
+  }
+  return elapsedMs < 120000 ? "🐣" : SPECIES_CONFIG[species].hatchedEmoji;
+}
+
+async function checkCurlFailure(
+  instanceName: string,
+  project: string,
+  zone: string,
+): Promise<boolean> {
+  try {
+    const output = await execOutput("gcloud", [
+      "compute",
+      "ssh",
+      instanceName,
+      `--project=${project}`,
+      `--zone=${zone}`,
+      "--quiet",
+      "--ssh-flag=-o StrictHostKeyChecking=no",
+      "--ssh-flag=-o UserKnownHostsFile=/dev/null",
+      "--ssh-flag=-o ConnectTimeout=10",
+      "--ssh-flag=-o LogLevel=ERROR",
+      `--command=test -s ${INSTALL_SCRIPT_REMOTE_PATH} && echo EXISTS || echo MISSING`,
+    ]);
+    return output.trim() === "MISSING";
+  } catch {
+    return false;
+  }
+}
+
+async function recoverFromCurlFailure(
+  instanceName: string,
+  project: string,
+  zone: string,
+  sshUser: string,
+): Promise<void> {
+  if (!existsSync(INSTALL_SCRIPT_PATH)) {
+    throw new Error(`Install script not found at ${INSTALL_SCRIPT_PATH}`);
+  }
+
+  console.log("📋 Uploading install script to instance...");
+  await exec("gcloud", [
+    "compute",
+    "scp",
+    INSTALL_SCRIPT_PATH,
+    `${instanceName}:${INSTALL_SCRIPT_REMOTE_PATH}`,
+    `--zone=${zone}`,
+    `--project=${project}`,
+  ]);
+
+  console.log("🔧 Running install script on instance...");
+  await exec("gcloud", [
+    "compute",
+    "ssh",
+    `${sshUser}@${instanceName}`,
+    `--zone=${zone}`,
+    `--project=${project}`,
+    `--command=source ${INSTALL_SCRIPT_REMOTE_PATH}`,
+  ]);
+}
+
+async function watchHatching(
+  instanceName: string,
+  project: string,
+  zone: string,
+  startTime: number,
+  species: Species,
+): Promise<boolean> {
+  let spinnerIdx = 0;
+  let lastLogLine: string | null = null;
+  let linesDrawn = 0;
+  let finished = false;
+  let failed = false;
+  let pollInFlight = false;
+  let nextPollAt = Date.now() + 15000;
+
+  function draw(): void {
+    if (linesDrawn > 0) {
+      process.stdout.write(`\x1b[${linesDrawn}A`);
+    }
+
+    const elapsed = Date.now() - startTime;
+
+    const hasLogs = lastLogLine !== null;
+    const icon = finished
+      ? failed
+        ? "💀"
+        : SPECIES_CONFIG[species].hatchedEmoji
+      : getPhaseIcon(hasLogs, elapsed, species);
+    const spinner = finished
+      ? failed
+        ? "✘"
+        : "✔"
+      : SPINNER_FRAMES[spinnerIdx % SPINNER_FRAMES.length];
+    const config = SPECIES_CONFIG[species];
+    const message = finished
+      ? failed
+        ? "❌ Startup script failed"
+        : "✨ Your assistant has hatched!"
+      : hasLogs
+        ? lastLogLine!.length > 68
+          ? lastLogLine!.substring(0, 65) + "..."
+          : lastLogLine!
+        : pickMessage(config.waitingMessages, elapsed);
+    spinnerIdx++;
+
+    const lines = ["", `   ${icon} ${spinner}  ${message}  ⏱  ${formatElapsed(elapsed)}`, ""];
+
+    for (const line of lines) {
+      process.stdout.write(`\x1b[K${line}\n`);
+    }
+    linesDrawn = lines.length;
+  }
+
+  async function poll(): Promise<void> {
+    if (pollInFlight || finished) return;
+    pollInFlight = true;
+    try {
+      const result = await pollInstance(instanceName, project, zone);
+      if (result.lastLine) {
+        lastLogLine = result.lastLine;
+      }
+      if (result.done) {
+        finished = true;
+        failed = result.failed;
+      }
+    } finally {
+      pollInFlight = false;
+      nextPollAt = Date.now() + 5000;
+    }
+  }
+
+  return new Promise<boolean>((resolve) => {
+    const interval = setInterval(() => {
+      if (finished) {
+        draw();
+        clearInterval(interval);
+        resolve(!failed);
+        return;
+      }
+
+      const elapsed = Date.now() - startTime;
+      if (elapsed >= HATCH_TIMEOUT_MS) {
+        clearInterval(interval);
+        console.log("");
+        console.log(`   ⏰ Timed out after ${formatElapsed(elapsed)}. Instance is still running.`);
+        console.log(`   Monitor with: vel logs ${instanceName}`);
+        console.log("");
+        resolve(true);
+        return;
+      }
+
+      if (Date.now() >= nextPollAt) {
+        poll();
+      }
+
+      draw();
+    }, 80);
+
+    process.on("SIGINT", () => {
+      clearInterval(interval);
+      console.log("");
+      console.log(`   ⚠️  Detaching. Instance is still running.`);
+      console.log(`   Monitor with: vel logs ${instanceName}`);
+      console.log("");
+      process.exit(0);
+    });
+  });
+}
+
+interface CloudCredentials {
+  provider: string;
+  projectId?: string;
+  serviceAccountKey?: string;
+}
+
+interface WorkspaceConfig {
+  cloudCredentials?: CloudCredentials;
+}
+
+async function activateGcpCredentialsFromConfig(): Promise<void> {
+  const configPath = join(homedir(), ".vellum", "workspace", "config.json");
+  let config: WorkspaceConfig;
+  try {
+    config = JSON.parse(readFileSync(configPath, "utf8")) as WorkspaceConfig;
+  } catch {
+    return;
+  }
+
+  const creds = config.cloudCredentials;
+  if (!creds || creds.provider !== "gcp" || !creds.serviceAccountKey || !creds.projectId) {
+    return;
+  }
+
+  const keyPath = join(tmpdir(), `vellum-sa-key-${Date.now()}.json`);
+  writeFileSync(keyPath, creds.serviceAccountKey);
+  try {
+    await exec("gcloud", [
+      "auth",
+      "activate-service-account",
+      `--key-file=${keyPath}`,
+    ]);
+    await exec("gcloud", ["config", "set", "project", creds.projectId]);
+  } finally {
+    try {
+      unlinkSync(keyPath);
+    } catch {}
+  }
+}
+
+async function hatchGcp(
+  species: Species,
+  detached: boolean,
+  name: string | null,
+): Promise<void> {
+  const startTime = Date.now();
+  try {
+    await activateGcpCredentialsFromConfig();
+    const project = process.env.GCP_PROJECT ?? (await getActiveProject());
+    let instanceName: string;
+
+    if (name) {
+      instanceName = name;
+    } else {
+      const suffix = generateRandomSuffix();
+      instanceName = `${species}-${suffix}`;
+    }
+
+    console.log(`🥚 Creating new assistant: ${instanceName}`);
+    console.log(`   Species: ${species}`);
+    console.log(`   Cloud: GCP`);
+    console.log(`   Project: ${project}`);
+    console.log(`   Zone: ${DEFAULT_ZONE}`);
+    console.log(`   Machine type: ${MACHINE_TYPE}`);
+    console.log("");
+
+    if (name) {
+      if (await instanceExists(name, project, DEFAULT_ZONE)) {
+        console.error(
+          `Error: Instance name '${name}' is already taken. Please choose a different name.`,
+        );
+        process.exit(1);
+      }
+    } else {
+      while (await instanceExists(instanceName, project, DEFAULT_ZONE)) {
+        console.log(`⚠️  Instance name ${instanceName} already exists, generating a new name...`);
+        const suffix = generateRandomSuffix();
+        instanceName = `${species}-${suffix}`;
+      }
+    }
+
+    const sshUser = userInfo().username;
+    const bearerToken = randomBytes(32).toString("hex");
+    const anthropicApiKey = process.env.ANTHROPIC_API_KEY;
+    if (!anthropicApiKey) {
+      console.error("Error: ANTHROPIC_API_KEY environment variable is not set.");
+      process.exit(1);
+    }
+    const startupScript = buildStartupScript(species, bearerToken, sshUser, anthropicApiKey);
+    const startupScriptPath = join(tmpdir(), `${instanceName}-startup.sh`);
+    writeFileSync(startupScriptPath, startupScript);
+
+    console.log("🔨 Creating instance with startup script...");
+    try {
+      await exec("gcloud", [
+        "compute",
+        "instances",
+        "create",
+        instanceName,
+        `--project=${project}`,
+        `--zone=${DEFAULT_ZONE}`,
+        `--machine-type=${MACHINE_TYPE}`,
+        "--image-family=debian-11",
+        "--image-project=debian-cloud",
+        "--boot-disk-size=50GB",
+        "--boot-disk-type=pd-standard",
+        `--metadata-from-file=startup-script=${startupScriptPath}`,
+        `--labels=species=${species},vellum-assistant=true`,
+        "--tags=vellum-assistant",
+      ]);
+    } finally {
+      try {
+        unlinkSync(startupScriptPath);
+      } catch {}
+    }
+
+    console.log("🔒 Syncing firewall rules...");
+    await syncFirewallRules(DESIRED_FIREWALL_RULES, project, FIREWALL_TAG);
+
+    console.log(`✅ Instance ${instanceName} created successfully\n`);
+
+    let externalIp: string | null = null;
+    try {
+      const ipOutput = await execOutput("gcloud", [
+        "compute",
+        "instances",
+        "describe",
+        instanceName,
+        `--project=${project}`,
+        `--zone=${DEFAULT_ZONE}`,
+        "--format=get(networkInterfaces[0].accessConfigs[0].natIP)",
+      ]);
+      externalIp = ipOutput.trim() || null;
+    } catch {
+      console.log("⚠️  Could not retrieve external IP yet (instance may still be starting)");
+    }
+
+    const runtimeUrl = externalIp
+      ? `http://${externalIp}:${GATEWAY_PORT}`
+      : `http://${instanceName}:${GATEWAY_PORT}`;
+    const entryFilePath = process.env.VELLUM_HATCH_ENTRY_FILE;
+    if (entryFilePath) {
+      writeFileSync(
+        entryFilePath,
+        JSON.stringify({
+          assistantId: instanceName,
+          runtimeUrl,
+          bearerToken,
+          project,
+          zone: DEFAULT_ZONE,
+          species,
+          sshUser,
+          hatchedAt: new Date().toISOString(),
+        }),
+      );
+    }
+
+    if (detached) {
+      console.log("🚀 Startup script is running on the instance...");
+      console.log("");
+      console.log("✅ Assistant is hatching!\n");
+      console.log("Instance details:");
+      console.log(`  Name: ${instanceName}`);
+      console.log(`  Project: ${project}`);
+      console.log(`  Zone: ${DEFAULT_ZONE}`);
+      if (externalIp) {
+        console.log(`  External IP: ${externalIp}`);
+      }
+      console.log("");
+    } else {
+      console.log("   Press Ctrl+C to detach (instance will keep running)");
+      console.log("");
+
+      const success = await watchHatching(
+        instanceName,
+        project,
+        DEFAULT_ZONE,
+        startTime,
+        species,
+      );
+
+      if (!success) {
+        if (
+          species === "vellum" &&
+          (await checkCurlFailure(instanceName, project, DEFAULT_ZONE))
+        ) {
+          console.log("");
+          console.log("🔄 Detected install script curl failure, attempting recovery...");
+          await recoverFromCurlFailure(instanceName, project, DEFAULT_ZONE, sshUser);
+          console.log("✅ Recovery successful!");
+        } else {
+          console.log("");
+          process.exit(1);
+        }
+      }
+
+      console.log("Instance details:");
+      console.log(`  Name: ${instanceName}`);
+      console.log(`  Project: ${project}`);
+      console.log(`  Zone: ${DEFAULT_ZONE}`);
+      if (externalIp) {
+        console.log(`  External IP: ${externalIp}`);
+      }
+    }
+  } catch (error) {
+    console.error("❌ Error:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+function buildSshArgs(host: string): string[] {
+  return [
+    host,
+    "-o", "StrictHostKeyChecking=no",
+    "-o", "UserKnownHostsFile=/dev/null",
+    "-o", "ConnectTimeout=10",
+    "-o", "LogLevel=ERROR",
+  ];
+}
+
+function extractHostname(host: string): string {
+  return host.includes("@") ? host.split("@")[1] : host;
+}
+
+async function hatchCustom(
+  species: Species,
+  detached: boolean,
+  name: string | null,
+): Promise<void> {
+  const host = process.env.VELLUM_CUSTOM_HOST;
+  if (!host) {
+    console.error("Error: VELLUM_CUSTOM_HOST environment variable is required when using --remote custom (e.g., user@hostname)");
+    process.exit(1);
+  }
+
+  try {
+    const hostname = extractHostname(host);
+    const instanceName = name ?? `${species}-${generateRandomSuffix()}`;
+
+    console.log(`🥚 Creating new assistant: ${instanceName}`);
+    console.log(`   Species: ${species}`);
+    console.log(`   Cloud: Custom`);
+    console.log(`   Host: ${host}`);
+    console.log("");
+
+    const sshUser = host.includes("@") ? host.split("@")[0] : userInfo().username;
+    const bearerToken = randomBytes(32).toString("hex");
+    const anthropicApiKey = process.env.ANTHROPIC_API_KEY;
+    if (!anthropicApiKey) {
+      console.error("Error: ANTHROPIC_API_KEY environment variable is not set.");
+      process.exit(1);
+    }
+
+    const startupScript = buildStartupScript(species, bearerToken, sshUser, anthropicApiKey);
+    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}`,
+      ]);
+
+      console.log("📋 Uploading startup script to instance...");
+      const remoteStartupPath = `/tmp/${instanceName}-startup.sh`;
+      await exec("scp", [
+        "-o", "StrictHostKeyChecking=no",
+        "-o", "UserKnownHostsFile=/dev/null",
+        "-o", "LogLevel=ERROR",
+        startupScriptPath,
+        `${host}:${remoteStartupPath}`,
+      ]);
+
+      console.log("🔨 Running startup script on instance...");
+      await exec("ssh", [
+        ...buildSshArgs(host),
+        `chmod +x ${remoteStartupPath} ${INSTALL_SCRIPT_REMOTE_PATH} && bash ${remoteStartupPath}`,
+      ]);
+    } finally {
+      try {
+        unlinkSync(startupScriptPath);
+      } catch {}
+    }
+
+    const runtimeUrl = `http://${hostname}:${GATEWAY_PORT}`;
+    const entryFilePath = process.env.VELLUM_HATCH_ENTRY_FILE;
+    if (entryFilePath) {
+      writeFileSync(
+        entryFilePath,
+        JSON.stringify({
+          assistantId: instanceName,
+          runtimeUrl,
+          bearerToken,
+          species,
+          sshUser,
+          hatchedAt: new Date().toISOString(),
+        }),
+      );
+    }
+
+    if (detached) {
+      console.log("");
+      console.log("✅ Assistant is hatching!\n");
+    } else {
+      console.log("");
+      console.log("✅ Assistant has been set up!");
+    }
+    console.log("Instance details:");
+    console.log(`  Name: ${instanceName}`);
+    console.log(`  Host: ${host}`);
+    console.log(`  Runtime URL: ${runtimeUrl}`);
+    console.log("");
+  } catch (error) {
+    console.error("❌ Error:", error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+async function hatchLocal(species: Species, name: string | null): Promise<void> {
+  const instanceName = name ?? `${species}-${generateRandomSuffix()}`;
+
+  console.log(`🥚 Hatching local assistant: ${instanceName}`);
+  console.log(`   Species: ${species}`);
+  console.log("");
+
+  console.log("🔨 Starting local daemon...");
+  const child = spawn("bunx", ["vellum", "daemon", "start"], {
+    stdio: "inherit",
+    env: { ...process.env },
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Daemon start exited with code ${code}`));
+      }
+    });
+    child.on("error", reject);
+  });
+
+  const runtimeUrl = `http://localhost:${GATEWAY_PORT}`;
+  const entryFilePath = process.env.VELLUM_HATCH_ENTRY_FILE;
+  if (entryFilePath) {
+    writeFileSync(
+      entryFilePath,
+      JSON.stringify({
+        assistantId: instanceName,
+        runtimeUrl,
+        species,
+        hatchedAt: new Date().toISOString(),
+      }),
+    );
+  }
+
+  console.log("");
+  console.log(`✅ Local assistant hatched!`);
+  console.log("");
+  console.log("Instance details:");
+  console.log(`  Name: ${instanceName}`);
+  console.log(`  Runtime: ${runtimeUrl}`);
+  console.log("");
+}
+
+export async function hatch(): Promise<void> {
+  const { species, detached, name, remote } = parseArgs();
+
+  if (remote === "local") {
+    await hatchLocal(species, name);
+    return;
+  }
+
+  if (remote === "gcp") {
+    await hatchGcp(species, detached, name);
+    return;
+  }
+
+  if (remote === "custom") {
+    await hatchCustom(species, detached, name);
+    return;
+  }
+
+  console.error(`Error: Remote host '${remote}' is not yet supported.`);
+  process.exit(1);
+}