@vellumai/cli 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,97 @@
+# @vellumai/cli
+
+CLI tools for provisioning and managing Vellum assistant instances.
+
+## Installation
+
+This package is used internally by the [`vel`](https://github.com/vellum-ai/vellum-assistant-platform/tree/main/vel) CLI. You typically don't need to install it directly.
+
+To run it standalone with [Bun](https://bun.sh):
+
+```bash
+bun run ./src/index.ts <command> [options]
+```
+
+## Commands
+
+### `hatch`
+
+Provision a new assistant instance and bootstrap the Vellum runtime on it.
+
+```bash
+vellum-cli hatch [species] [options]
+```
+
+#### Species
+
+| Species    | Description                                 |
+| ---------- | ------------------------------------------- |
+| `vellum`   | Default. Provisions the Vellum assistant runtime. |
+| `openclaw` | Provisions the OpenClaw runtime with gateway. |
+
+#### Options
+
+| Option              | Description |
+| ------------------- | ----------- |
+| `-d`                | Detached mode. Start the instance in the background without watching startup progress. |
+| `--name <name>`     | Use a specific instance name instead of an auto-generated one. |
+| `--remote <target>` | Where to provision the instance. One of: `local`, `gcp`, `aws`, `custom`. Defaults to `local`. |
+
+#### Remote Targets
+
+- **`local`** -- Starts a local daemon on your machine via `bunx vellum daemon start`.
+- **`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.
+
+#### Environment Variables
+
+| Variable              | Required For | Description |
+| --------------------- | ------------ | ----------- |
+| `ANTHROPIC_API_KEY`   | All             | Anthropic API key passed to the assistant runtime. |
+| `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. |
+
+#### Examples
+
+```bash
+# Hatch a local assistant (default)
+vellum-cli hatch
+
+# Hatch a vellum assistant on GCP
+vellum-cli hatch vellum --remote gcp
+
+# Hatch an openclaw assistant on GCP in detached mode
+vellum-cli hatch openclaw --remote gcp -d
+
+# Hatch with a specific instance name
+vellum-cli hatch --name my-assistant --remote gcp
+
+# Hatch on a custom SSH host
+VELLUM_CUSTOM_HOST=user@10.0.0.1 vellum-cli hatch --remote custom
+```
+
+When hatching on GCP in interactive mode (without `-d`), the CLI displays an animated progress TUI that polls the instance's startup script output in real time. Press `Ctrl+C` to detach -- the instance will continue running in the background.
+
+### `retire`
+
+Delete a provisioned assistant instance. The cloud provider and connection details are automatically resolved from the saved assistant config (written during `hatch`).
+
+```bash
+vellum-cli retire <name>
+```
+
+The CLI looks up the instance by name in `~/.vellum.lock.json` and determines how to retire it based on the saved `cloud` field:
+
+- **`gcp`** -- Deletes the GCP Compute Engine instance via `gcloud compute instances delete`.
+- **`aws`** -- Terminates the AWS EC2 instance by looking up the instance ID from its Name tag.
+- **`local`** -- Stops the local daemon (`bunx vellum daemon stop`) and removes the `~/.vellum` directory.
+- **`custom`** -- SSHs to the remote host to stop the daemon/gateway and remove the `~/.vellum` directory.
+
+#### Examples
+
+```bash
+# Retire an instance (cloud type resolved from config)
+vellum-cli retire my-assistant
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "bin": {

package/src/adapters/openclaw.ts

@@ -97,7 +97,14 @@ else
   echo "bun already installed: $(bun --version)"
 fi
 
+set +e
 openclaw gateway install --token ${bearerToken}
+GATEWAY_INSTALL_EXIT=\$?
+set -e
+
+if [ \$GATEWAY_INSTALL_EXIT -ne 0 ]; then
+  echo "WARN: openclaw gateway install exited with \$GATEWAY_INSTALL_EXIT (expected systemd mismatch), continuing with user-level systemd setup"
+fi
 
 mkdir -p /root/.openclaw
 openclaw config set env.ANTHROPIC_API_KEY "${anthropicApiKey}"

package/src/commands/hatch.ts

@@ -1,10 +1,13 @@
 import { spawn } from "child_process";
 import { randomBytes } from "crypto";
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "fs";
-import { homedir, tmpdir, userInfo } from "os";
+import { existsSync, unlinkSync, writeFileSync } from "fs";
+import { tmpdir, userInfo } from "os";
 import { join } from "path";
 
 import { buildOpenclawStartupScript } from "../adapters/openclaw";
+import { saveAssistantEntry } from "../lib/assistant-config";
+import type { AssistantEntry } from "../lib/assistant-config";
+import { hatchAws } from "../lib/aws";
 import {
   FIREWALL_TAG,
   GATEWAY_PORT,
@@ -19,11 +22,13 @@ 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 HATCH_TIMEOUT_MS: Record<Species, number> = {
+  vellum: 2 * 60 * 1000,
+  openclaw: 10 * 60 * 1000,
+};
 const DEFAULT_SPECIES: Species = "vellum";
 
 const DESIRED_FIREWALL_RULES: FirewallRuleSpec[] = [
@@ -71,12 +76,13 @@ chown -R "$SSH_USER:$SSH_USER" "$SSH_USER_HOME" 2>/dev/null || true
 `;
 }
 
-function buildStartupScript(
+export function buildStartupScript(
   species: Species,
   bearerToken: string,
   sshUser: string,
   anthropicApiKey: string,
 ): string {
+  const platformUrl = process.env.VELLUM_ASSISTANT_PLATFORM_URL ?? "https://assistant.vellum.ai";
   const timestampRedirect = buildTimestampRedirect();
   const userSetup = buildUserSetup(sshUser);
   const ownershipFixup = buildOwnershipFixup();
@@ -125,7 +131,7 @@ CONFIG_EOF
 ${ownershipFixup}
 
 export VELLUM_SSH_USER="\$SSH_USER"
-curl -fsSL https://assistant.vellum.ai/install.sh -o ${INSTALL_SCRIPT_REMOTE_PATH}
+curl -fsSL ${platformUrl}/install.sh -o ${INSTALL_SCRIPT_REMOTE_PATH}
 chmod +x ${INSTALL_SCRIPT_REMOTE_PATH}
 source ${INSTALL_SCRIPT_REMOTE_PATH}
 `;
@@ -182,7 +188,7 @@ function parseArgs(): HatchArgs {
   return { species, detached, name, remote };
 }
 
-interface PollResult {
+export interface PollResult {
   lastLine: string | null;
   done: boolean;
   failed: boolean;
@@ -192,6 +198,7 @@ async function pollInstance(
   instanceName: string,
   project: string,
   zone: string,
+  account?: string,
 ): Promise<PollResult> {
   try {
     const remoteCmd =
@@ -199,7 +206,7 @@ async function pollInstance(
       "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", [
+    const args = [
       "compute",
       "ssh",
       instanceName,
@@ -211,7 +218,9 @@ async function pollInstance(
       "--ssh-flag=-o ConnectTimeout=10",
       "--ssh-flag=-o LogLevel=ERROR",
       `--command=${remoteCmd}`,
-    ]);
+    ];
+    if (account) args.push(`--account=${account}`);
+    const output = await execOutput("gcloud", args);
     const sepIdx = output.indexOf("===HATCH_SEP===");
     if (sepIdx === -1) {
       return { lastLine: output.trim() || null, done: false, failed: false };
@@ -253,9 +262,10 @@ async function checkCurlFailure(
   instanceName: string,
   project: string,
   zone: string,
+  account?: string,
 ): Promise<boolean> {
   try {
-    const output = await execOutput("gcloud", [
+    const args = [
       "compute",
       "ssh",
       instanceName,
@@ -267,7 +277,9 @@ async function checkCurlFailure(
       "--ssh-flag=-o ConnectTimeout=10",
       "--ssh-flag=-o LogLevel=ERROR",
       `--command=test -s ${INSTALL_SCRIPT_REMOTE_PATH} && echo EXISTS || echo MISSING`,
-    ]);
+    ];
+    if (account) args.push(`--account=${account}`);
+    const output = await execOutput("gcloud", args);
     return output.trim() === "MISSING";
   } catch {
     return false;
@@ -279,36 +291,40 @@ async function recoverFromCurlFailure(
   project: string,
   zone: string,
   sshUser: string,
+  account?: 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", [
+  const scpArgs = [
     "compute",
     "scp",
     INSTALL_SCRIPT_PATH,
     `${instanceName}:${INSTALL_SCRIPT_REMOTE_PATH}`,
     `--zone=${zone}`,
     `--project=${project}`,
-  ]);
+  ];
+  if (account) scpArgs.push(`--account=${account}`);
+  console.log("📋 Uploading install script to instance...");
+  await exec("gcloud", scpArgs);
 
-  console.log("🔧 Running install script on instance...");
-  await exec("gcloud", [
+  const sshArgs = [
     "compute",
     "ssh",
     `${sshUser}@${instanceName}`,
     `--zone=${zone}`,
     `--project=${project}`,
     `--command=source ${INSTALL_SCRIPT_REMOTE_PATH}`,
-  ]);
+  ];
+  if (account) sshArgs.push(`--account=${account}`);
+  console.log("🔧 Running install script on instance...");
+  await exec("gcloud", sshArgs);
 }
 
-async function watchHatching(
+export async function watchHatching(
+  pollFn: () => Promise<PollResult>,
   instanceName: string,
-  project: string,
-  zone: string,
   startTime: number,
   species: Species,
 ): Promise<boolean> {
@@ -362,7 +378,7 @@ async function watchHatching(
     if (pollInFlight || finished) return;
     pollInFlight = true;
     try {
-      const result = await pollInstance(instanceName, project, zone);
+      const result = await pollFn();
       if (result.lastLine) {
         lastLogLine = result.lastLine;
       }
@@ -386,7 +402,7 @@ async function watchHatching(
       }
 
       const elapsed = Date.now() - startTime;
-      if (elapsed >= HATCH_TIMEOUT_MS) {
+      if (elapsed >= HATCH_TIMEOUT_MS[species]) {
         clearInterval(interval);
         console.log("");
         console.log(`   ⏰ Timed out after ${formatElapsed(elapsed)}. Instance is still running.`);
@@ -414,45 +430,6 @@ async function watchHatching(
   });
 }
 
-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,
@@ -460,8 +437,8 @@ async function hatchGcp(
   name: string | null,
 ): Promise<void> {
   const startTime = Date.now();
+  const account = process.env.GCP_ACCOUNT_EMAIL;
   try {
-    await activateGcpCredentialsFromConfig();
     const project = process.env.GCP_PROJECT ?? (await getActiveProject());
     let instanceName: string;
 
@@ -476,19 +453,25 @@ async function hatchGcp(
     console.log(`   Species: ${species}`);
     console.log(`   Cloud: GCP`);
     console.log(`   Project: ${project}`);
-    console.log(`   Zone: ${DEFAULT_ZONE}`);
+    const zone = process.env.GCP_DEFAULT_ZONE;
+    if (!zone) {
+      console.error("Error: GCP_DEFAULT_ZONE environment variable is not set.");
+      process.exit(1);
+    }
+
+    console.log(`   Zone: ${zone}`);
     console.log(`   Machine type: ${MACHINE_TYPE}`);
     console.log("");
 
     if (name) {
-      if (await instanceExists(name, project, DEFAULT_ZONE)) {
+      if (await instanceExists(name, project, zone, account)) {
         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)) {
+      while (await instanceExists(instanceName, project, zone, account)) {
         console.log(`⚠️  Instance name ${instanceName} already exists, generating a new name...`);
         const suffix = generateRandomSuffix();
         instanceName = `${species}-${suffix}`;
@@ -508,13 +491,13 @@ async function hatchGcp(
 
     console.log("🔨 Creating instance with startup script...");
     try {
-      await exec("gcloud", [
+      const createArgs = [
         "compute",
         "instances",
         "create",
         instanceName,
         `--project=${project}`,
-        `--zone=${DEFAULT_ZONE}`,
+        `--zone=${zone}`,
         `--machine-type=${MACHINE_TYPE}`,
         "--image-family=debian-11",
         "--image-project=debian-cloud",
@@ -523,7 +506,9 @@ async function hatchGcp(
         `--metadata-from-file=startup-script=${startupScriptPath}`,
         `--labels=species=${species},vellum-assistant=true`,
         "--tags=vellum-assistant",
-      ]);
+      ];
+      if (account) createArgs.push(`--account=${account}`);
+      await exec("gcloud", createArgs);
     } finally {
       try {
         unlinkSync(startupScriptPath);
@@ -531,21 +516,23 @@ async function hatchGcp(
     }
 
     console.log("🔒 Syncing firewall rules...");
-    await syncFirewallRules(DESIRED_FIREWALL_RULES, project, FIREWALL_TAG);
+    await syncFirewallRules(DESIRED_FIREWALL_RULES, project, FIREWALL_TAG, account);
 
     console.log(`✅ Instance ${instanceName} created successfully\n`);
 
     let externalIp: string | null = null;
     try {
-      const ipOutput = await execOutput("gcloud", [
+      const describeArgs = [
         "compute",
         "instances",
         "describe",
         instanceName,
         `--project=${project}`,
-        `--zone=${DEFAULT_ZONE}`,
+        `--zone=${zone}`,
         "--format=get(networkInterfaces[0].accessConfigs[0].natIP)",
-      ]);
+      ];
+      if (account) describeArgs.push(`--account=${account}`);
+      const ipOutput = await execOutput("gcloud", describeArgs);
       externalIp = ipOutput.trim() || null;
     } catch {
       console.log("⚠️  Could not retrieve external IP yet (instance may still be starting)");
@@ -554,22 +541,18 @@ async function hatchGcp(
     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(),
-        }),
-      );
-    }
+    const gcpEntry: AssistantEntry = {
+      assistantId: instanceName,
+      runtimeUrl,
+      bearerToken,
+      cloud: "gcp",
+      project,
+      zone,
+      species,
+      sshUser,
+      hatchedAt: new Date().toISOString(),
+    };
+    saveAssistantEntry(gcpEntry);
 
     if (detached) {
       console.log("🚀 Startup script is running on the instance...");
@@ -578,7 +561,7 @@ async function hatchGcp(
       console.log("Instance details:");
       console.log(`  Name: ${instanceName}`);
       console.log(`  Project: ${project}`);
-      console.log(`  Zone: ${DEFAULT_ZONE}`);
+      console.log(`  Zone: ${zone}`);
       if (externalIp) {
         console.log(`  External IP: ${externalIp}`);
       }
@@ -588,9 +571,8 @@ async function hatchGcp(
       console.log("");
 
       const success = await watchHatching(
+        () => pollInstance(instanceName, project, zone, account),
         instanceName,
-        project,
-        DEFAULT_ZONE,
         startTime,
         species,
       );
@@ -598,11 +580,11 @@ async function hatchGcp(
       if (!success) {
         if (
           species === "vellum" &&
-          (await checkCurlFailure(instanceName, project, DEFAULT_ZONE))
+          (await checkCurlFailure(instanceName, project, zone, account))
         ) {
           console.log("");
           console.log("🔄 Detected install script curl failure, attempting recovery...");
-          await recoverFromCurlFailure(instanceName, project, DEFAULT_ZONE, sshUser);
+          await recoverFromCurlFailure(instanceName, project, zone, sshUser, account);
           console.log("✅ Recovery successful!");
         } else {
           console.log("");
@@ -613,7 +595,7 @@ async function hatchGcp(
       console.log("Instance details:");
       console.log(`  Name: ${instanceName}`);
       console.log(`  Project: ${project}`);
-      console.log(`  Zone: ${DEFAULT_ZONE}`);
+      console.log(`  Zone: ${zone}`);
       if (externalIp) {
         console.log(`  External IP: ${externalIp}`);
       }
@@ -703,20 +685,16 @@ async function hatchCustom(
     }
 
     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(),
-        }),
-      );
-    }
+    const customEntry: AssistantEntry = {
+      assistantId: instanceName,
+      runtimeUrl,
+      bearerToken,
+      cloud: "custom",
+      species,
+      sshUser,
+      hatchedAt: new Date().toISOString(),
+    };
+    saveAssistantEntry(customEntry);
 
     if (detached) {
       console.log("");
@@ -760,20 +738,36 @@ async function hatchLocal(species: Species, name: string | null): Promise<void>
     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("🌐 Starting gateway...");
+  const gatewayDir = join(import.meta.dir, "..", "..", "..", "gateway");
+  if (!existsSync(gatewayDir)) {
+    console.warn("⚠️  Gateway directory not found at", gatewayDir);
+    console.warn('   Gateway will not be started\n');
+  } else {
+    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",
+      },
+    });
+    gateway.unref();
+    console.log("✅ Gateway started\n");
   }
 
+  const runtimeUrl = `http://localhost:${GATEWAY_PORT}`;
+  const localEntry: AssistantEntry = {
+    assistantId: instanceName,
+    runtimeUrl,
+    cloud: "local",
+    species,
+    hatchedAt: new Date().toISOString(),
+  };
+  saveAssistantEntry(localEntry);
+
   console.log("");
   console.log(`✅ Local assistant hatched!`);
   console.log("");
@@ -801,6 +795,11 @@ export async function hatch(): Promise<void> {
     return;
   }
 
+  if (remote === "aws") {
+    await hatchAws(species, detached, name);
+    return;
+  }
+
   console.error(`Error: Remote host '${remote}' is not yet supported.`);
   process.exit(1);
 }