@vellumai/cli 0.6.2 → 0.6.4

package/src/commands/upgrade.ts

@@ -189,18 +189,9 @@ async function upgradeDocker(
   const versionTag =
     version ?? (cliPkg.version ? `v${cliPkg.version}` : "latest");
 
-  // Reject downgrades — `vellum upgrade` only handles forward version changes.
-  // Users should use `vellum rollback --version <version>` for downgrades.
-  const currentVersion = entry.serviceGroupVersion;
-  if (currentVersion && versionTag) {
-    const cmp = compareVersions(versionTag, currentVersion);
-    if (cmp !== null && cmp < 0) {
-      const msg = `Cannot upgrade to an older version (${versionTag} < ${currentVersion}). Use \`vellum rollback --version ${versionTag}\` instead.`;
-      console.error(msg);
-      emitCliError("VERSION_DIRECTION", msg);
-      process.exit(1);
-    }
-  }
+  // Fetch the current running version from the health endpoint.
+  // This is used for logging, commit messages, and version-direction guards.
+  let currentVersion: string | undefined;
 
   console.log("🔍 Resolving image references...");
   const { imageTags } = await resolveImageRefs(versionTag);
@@ -225,7 +216,7 @@ async function upgradeDocker(
     );
   }
 
-  // Capture current migration state for rollback targeting.
+  // Capture current migration state and running version for rollback targeting.
   // Must happen while daemon is still running (before containers are stopped).
   let preMigrationState: {
     dbVersion?: number;
@@ -240,26 +231,47 @@ async function upgradeDocker(
     );
     if (healthResp.ok) {
       const health = (await healthResp.json()) as {
+        version?: string;
         migrations?: { dbVersion?: number; lastWorkspaceMigrationId?: string };
       };
       preMigrationState = health.migrations ?? {};
+      currentVersion = health.version;
     }
   } catch {
     // Best-effort — if we can't get migration state, rollback will skip migration reversal
   }
 
+  // Reject downgrades — `vellum upgrade` only handles forward version changes.
+  // Users should use `vellum rollback --version <version>` for downgrades.
+  if (!currentVersion && versionTag) {
+    console.warn(
+      "⚠️  Could not determine current version from health endpoint — skipping version-direction check.\n",
+    );
+  }
+  if (currentVersion && versionTag) {
+    const cmp = compareVersions(versionTag, currentVersion);
+    if (cmp !== null && cmp < 0) {
+      const msg = `Cannot upgrade to an older version (${versionTag} < ${currentVersion}). Use \`vellum rollback --version ${versionTag}\` instead.`;
+      console.error(msg);
+      emitCliError("VERSION_DIRECTION", msg);
+      process.exit(1);
+    }
+  }
+
   // Persist rollback state to lockfile BEFORE any destructive changes.
   // This enables the `vellum rollback` command to restore the previous version.
-  if (entry.serviceGroupVersion && entry.containerInfo) {
+  if (entry.containerInfo) {
     const rollbackEntry: AssistantEntry = {
       ...entry,
-      previousServiceGroupVersion: entry.serviceGroupVersion,
       previousContainerInfo: { ...entry.containerInfo },
+      previousVersion: currentVersion,
       previousDbMigrationVersion: preMigrationState.dbVersion,
       previousWorkspaceMigrationId: preMigrationState.lastWorkspaceMigrationId,
     };
     saveAssistantEntry(rollbackEntry);
-    console.log(`   Saved rollback state: ${entry.serviceGroupVersion}\n`);
+    if (currentVersion) {
+      console.log(`   Saved rollback state: ${currentVersion}\n`);
+    }
   }
 
   // Record version transition start in workspace git history
@@ -269,7 +281,7 @@ async function upgradeDocker(
     buildUpgradeCommitMessage({
       action: "upgrade",
       phase: "starting",
-      from: entry.serviceGroupVersion ?? "unknown",
+      from: currentVersion ?? "unknown",
       to: versionTag,
       topology: "docker",
       assistantId: entry.assistantId,
@@ -321,7 +333,7 @@ async function upgradeDocker(
     await broadcastUpgradeEvent(
       entry.runtimeUrl,
       entry.assistantId,
-      buildCompleteEvent(entry.serviceGroupVersion ?? "unknown", false),
+      buildCompleteEvent(currentVersion ?? "unknown", false),
     );
     emitCliError("IMAGE_PULL_FAILED", "Failed to pull Docker images", detail);
     process.exit(1);
@@ -361,7 +373,7 @@ async function upgradeDocker(
   console.log("📦 Creating pre-upgrade backup...");
   const backupPath = await createBackup(entry.runtimeUrl, entry.assistantId, {
     prefix: `${entry.assistantId}-pre-upgrade`,
-    description: `Pre-upgrade snapshot before ${entry.serviceGroupVersion ?? "unknown"} → ${versionTag}`,
+    description: `Pre-upgrade snapshot before ${currentVersion ?? "unknown"} → ${versionTag}`,
   });
   if (backupPath) {
     console.log(`   Backup saved: ${backupPath}\n`);
@@ -434,7 +446,6 @@ async function upgradeDocker(
     const newDigests = await captureImageRefs(res);
     const updatedEntry: AssistantEntry = {
       ...entry,
-      serviceGroupVersion: versionTag,
       containerInfo: {
         assistantImage: imageTags.assistant,
         gatewayImage: imageTags.gateway,
@@ -444,7 +455,6 @@ async function upgradeDocker(
         cesDigest: newDigests?.["credential-executor"],
         networkName: res.network,
       },
-      previousServiceGroupVersion: entry.serviceGroupVersion,
       previousContainerInfo: entry.containerInfo,
       previousDbMigrationVersion: preMigrationState.dbVersion,
       previousWorkspaceMigrationId: preMigrationState.lastWorkspaceMigrationId,
@@ -467,7 +477,7 @@ async function upgradeDocker(
       buildUpgradeCommitMessage({
         action: "upgrade",
         phase: "complete",
-        from: entry.serviceGroupVersion ?? "unknown",
+        from: currentVersion ?? "unknown",
         to: versionTag,
         topology: "docker",
         assistantId: entry.assistantId,
@@ -584,7 +594,6 @@ async function upgradeDocker(
                 previousImageRefs["credential-executor"],
               networkName: res.network,
             },
-            previousServiceGroupVersion: undefined,
             previousContainerInfo: undefined,
             previousDbMigrationVersion: undefined,
             previousWorkspaceMigrationId: undefined,
@@ -598,9 +607,9 @@ async function upgradeDocker(
             entry.runtimeUrl,
             entry.assistantId,
             buildCompleteEvent(
-              entry.serviceGroupVersion ?? "unknown",
+              currentVersion ?? "unknown",
               false,
-              entry.serviceGroupVersion,
+              currentVersion,
             ),
           );
 
@@ -621,7 +630,7 @@ async function upgradeDocker(
           await broadcastUpgradeEvent(
             entry.runtimeUrl,
             entry.assistantId,
-            buildCompleteEvent(entry.serviceGroupVersion ?? "unknown", false),
+            buildCompleteEvent(currentVersion ?? "unknown", false),
           );
           emitCliError(
             "ROLLBACK_FAILED",
@@ -641,7 +650,7 @@ async function upgradeDocker(
         await broadcastUpgradeEvent(
           entry.runtimeUrl,
           entry.assistantId,
-          buildCompleteEvent(entry.serviceGroupVersion ?? "unknown", false),
+          buildCompleteEvent(currentVersion ?? "unknown", false),
         );
         emitCliError(
           "ROLLBACK_FAILED",
@@ -657,7 +666,7 @@ async function upgradeDocker(
       await broadcastUpgradeEvent(
         entry.runtimeUrl,
         entry.assistantId,
-        buildCompleteEvent(entry.serviceGroupVersion ?? "unknown", false),
+        buildCompleteEvent(currentVersion ?? "unknown", false),
       );
       emitCliError(
         "ROLLBACK_NO_STATE",
@@ -678,22 +687,6 @@ async function upgradePlatform(
   entry: AssistantEntry,
   version: string | null,
 ): Promise<void> {
-  // Reject downgrades — `vellum upgrade` only handles forward version changes.
-  // Users should use `vellum rollback --version <version>` for downgrades.
-  // Only enforce this guard when the user explicitly passed `--version`.
-  // When version is null the platform API decides the actual target, so
-  // we must not block the request based on the local CLI version.
-  const currentVersion = entry.serviceGroupVersion;
-  if (version && currentVersion) {
-    const cmp = compareVersions(version, currentVersion);
-    if (cmp !== null && cmp < 0) {
-      const msg = `Cannot upgrade to an older version (${version} < ${currentVersion}). Use \`vellum rollback --version ${version}\` instead.`;
-      console.error(msg);
-      emitCliError("VERSION_DIRECTION", msg);
-      process.exit(1);
-    }
-  }
-
   console.log(
     `🔄 Upgrading platform-hosted assistant '${entry.assistantId}'...\n`,
   );
@@ -733,7 +726,7 @@ async function upgradePlatform(
       await broadcastUpgradeEvent(
         entry.runtimeUrl,
         entry.assistantId,
-        buildCompleteEvent(entry.serviceGroupVersion ?? "unknown", false),
+        buildCompleteEvent("unknown", false),
       );
     } catch {
       // Best-effort — broadcast may fail if the assistant is unreachable
@@ -755,7 +748,7 @@ async function upgradePlatform(
       await broadcastUpgradeEvent(
         entry.runtimeUrl,
         entry.assistantId,
-        buildCompleteEvent(entry.serviceGroupVersion ?? "unknown", false),
+        buildCompleteEvent("unknown", false),
       );
     } catch {
       // Best-effort — broadcast may fail if the assistant is unreachable
@@ -788,8 +781,8 @@ async function upgradePrepare(
   entry: AssistantEntry,
   version: string | null,
 ): Promise<void> {
-  const targetVersion = version ?? entry.serviceGroupVersion ?? "unknown";
-  const currentVersion = entry.serviceGroupVersion ?? "unknown";
+  const targetVersion = version ?? "unknown";
+  const currentVersion = "unknown";
 
   // 1. Broadcast "starting" so the UI shows the progress spinner
   await broadcastUpgradeEvent(
@@ -857,9 +850,7 @@ async function upgradeFinalize(
   }
 
   const fromVersion = version;
-  const currentVersion = cliPkg.version
-    ? `v${cliPkg.version}`
-    : (entry.serviceGroupVersion ?? "unknown");
+  const currentVersion = cliPkg.version ? `v${cliPkg.version}` : "unknown";
 
   // 1. Broadcast "complete" so the UI clears the progress spinner
   await broadcastUpgradeEvent(
@@ -911,7 +902,7 @@ export async function upgrade(): Promise<void> {
     await broadcastUpgradeEvent(
       entry.runtimeUrl,
       entry.assistantId,
-      buildCompleteEvent(entry.serviceGroupVersion ?? "unknown", false),
+      buildCompleteEvent("unknown", false),
     );
     emitCliError(categorizeUpgradeError(err), "Upgrade failed", detail);
     process.exit(1);

package/src/commands/wake.ts

@@ -59,6 +59,13 @@ export async function wake(): Promise<void> {
     return;
   }
 
+  if (entry.cloud === "apple-container") {
+    console.error(
+      `Error: '${entry.assistantId}' uses the Apple Containers runtime. Its lifecycle is managed by the macOS app — use the app to start it.`,
+    );
+    process.exit(1);
+  }
+
   if (entry.cloud && entry.cloud !== "local") {
     console.error(
       `Error: 'vellum wake' only works with local and docker assistants. '${entry.assistantId}' is a ${entry.cloud} instance.`,
@@ -176,18 +183,22 @@ export async function wake(): Promise<void> {
   }
 
   // Auto-start ngrok if webhook integrations (e.g. Telegram) are configured.
-  // Set BASE_DATA_DIR so ngrok reads the correct instance config.
+  // Scope BASE_DATA_DIR to the woken instance so ngrok reads the correct
+  // instance config, then restore on any exit path.
   const prevBaseDataDir = process.env.BASE_DATA_DIR;
   process.env.BASE_DATA_DIR = resources.instanceDir;
-  const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
-  if (ngrokChild?.pid) {
-    const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
-    writeFileSync(ngrokPidFile, String(ngrokChild.pid));
-  }
-  if (prevBaseDataDir !== undefined) {
-    process.env.BASE_DATA_DIR = prevBaseDataDir;
-  } else {
-    delete process.env.BASE_DATA_DIR;
+  try {
+    const ngrokChild = await maybeStartNgrokTunnel(resources.gatewayPort);
+    if (ngrokChild?.pid) {
+      const ngrokPidFile = join(resources.instanceDir, ".vellum", "ngrok.pid");
+      writeFileSync(ngrokPidFile, String(ngrokChild.pid));
+    }
+  } finally {
+    if (prevBaseDataDir !== undefined) {
+      process.env.BASE_DATA_DIR = prevBaseDataDir;
+    } else {
+      delete process.env.BASE_DATA_DIR;
+    }
   }
 
   console.log("Wake complete.");

package/src/components/DefaultMainScreen.tsx

@@ -1939,8 +1939,14 @@ function ChatApp({
             );
           }
 
+          let username: string;
+          try {
+            username = userInfo().username;
+          } catch {
+            username = "";
+          }
           const hostId = createHash("sha256")
-            .update(hostname() + userInfo().username)
+            .update(hostname() + username)
             .digest("hex");
           const payload = JSON.stringify({
             type: "vellum-assistant",

package/src/index.ts

@@ -7,6 +7,7 @@ import { client } from "./commands/client";
 import { events } from "./commands/events";
 import { hatch } from "./commands/hatch";
 import { login, logout, whoami } from "./commands/login";
+import { logs } from "./commands/logs";
 import { message } from "./commands/message";
 import { pair } from "./commands/pair";
 import { ps } from "./commands/ps";
@@ -39,6 +40,7 @@ const commands = {
   hatch,
   login,
   logout,
+  logs,
   message,
   pair,
   ps,
@@ -68,6 +70,7 @@ function printHelp(): void {
   console.log("  client   Connect to a hatched assistant");
   console.log("  events   Stream events from a running assistant");
   console.log("  hatch    Create a new assistant instance");
+  console.log("  logs     View logs from an assistant instance");
   console.log("  login    Log in to the Vellum platform");
   console.log("  logout   Log out of the Vellum platform");
   console.log("  message  Send a message to a running assistant");

package/src/lib/__tests__/docker.test.ts

@@ -0,0 +1,78 @@
+import { describe, test, expect } from "bun:test";
+import {
+  ASSISTANT_INTERNAL_PORT,
+  dockerResourceNames,
+  serviceDockerRunArgs,
+  type ServiceName,
+} from "../docker.js";
+
+const instanceName = "test-instance";
+const imageTags: Record<ServiceName, string> = {
+  assistant: "vellumai/vellum-assistant:test",
+  "credential-executor": "vellumai/vellum-credential-executor:test",
+  gateway: "vellumai/vellum-gateway:test",
+};
+
+function buildAssistantArgs(): string[] {
+  const res = dockerResourceNames(instanceName);
+  const builders = serviceDockerRunArgs({
+    gatewayPort: 7830,
+    imageTags,
+    instanceName,
+    res,
+  });
+  return builders.assistant();
+}
+
+describe("serviceDockerRunArgs — assistant", () => {
+  test("runs privileged so the inner dockerd can manage cgroups/iptables/overlayfs", () => {
+    const args = buildAssistantArgs();
+    expect(args).toContain("--privileged");
+  });
+
+  test("mounts a dedicated named volume at /var/lib/docker for the inner dockerd data store", () => {
+    const args = buildAssistantArgs();
+    const spec = `${instanceName}-dockerd-data:/var/lib/docker`;
+    const mountIndex = args.indexOf(spec);
+    expect(mountIndex).toBeGreaterThan(0);
+    expect(args[mountIndex - 1]).toBe("-v");
+  });
+
+  test("does NOT bind-mount the host Docker socket (DinD replaces host-socket access)", () => {
+    const args = buildAssistantArgs();
+    expect(args).not.toContain("/var/run/docker.sock:/var/run/docker.sock");
+  });
+
+  test("does NOT set VELLUM_WORKSPACE_VOLUME_NAME (legacy Phase 1.8 hint, no longer needed in DinD)", () => {
+    const args = buildAssistantArgs();
+    expect(
+      args.some((a) => a.startsWith("VELLUM_WORKSPACE_VOLUME_NAME=")),
+    ).toBe(false);
+  });
+
+  test("keeps existing workspace and socket volume mounts intact", () => {
+    const args = buildAssistantArgs();
+    expect(args).toContain(`${instanceName}-workspace:/workspace`);
+    expect(args).toContain(`${instanceName}-socket:/run/ces-bootstrap`);
+  });
+
+  test("preserves existing required env vars", () => {
+    const args = buildAssistantArgs();
+    expect(args).toContain("IS_CONTAINERIZED=true");
+    expect(args).toContain("VELLUM_WORKSPACE_DIR=/workspace");
+    expect(args).toContain(`VELLUM_ASSISTANT_NAME=${instanceName}`);
+  });
+
+  test("publishes the assistant HTTP port on all host interfaces so sibling bot containers can reach the daemon via host.docker.internal on both Docker Desktop and Linux", () => {
+    const args = buildAssistantArgs();
+    // The port mapping is expressed as two adjacent args: "-p" then the spec.
+    // Bound to all interfaces (no `127.0.0.1:` prefix) because on vanilla
+    // Linux Docker, host.docker.internal:host-gateway resolves to the Docker
+    // bridge gateway IP — packets arrive at the bridge interface, not
+    // loopback, so a 127.0.0.1 DNAT rule would not match.
+    const portSpec = `${ASSISTANT_INTERNAL_PORT}:${ASSISTANT_INTERNAL_PORT}`;
+    const portIndex = args.indexOf(portSpec);
+    expect(portIndex).toBeGreaterThan(0);
+    expect(args[portIndex - 1]).toBe("-p");
+  });
+});

package/src/lib/assistant-config.ts

@@ -8,7 +8,7 @@ import {
   writeFileSync,
 } from "fs";
 import { homedir } from "os";
-import { join } from "path";
+import { dirname, join } from "path";
 
 import {
   DAEMON_INTERNAL_ASSISTANT_ID,
@@ -16,8 +16,13 @@ import {
   DEFAULT_DAEMON_PORT,
   DEFAULT_GATEWAY_PORT,
   DEFAULT_QDRANT_PORT,
-  LOCKFILE_NAMES,
 } from "./constants.js";
+import {
+  getLockfilePath,
+  getLockfilePaths,
+  getMultiInstanceDir,
+} from "./environments/paths.js";
+import { getCurrentEnvironment } from "./environments/resolve.js";
 import { probePort } from "./port-probe.js";
 
 /**
@@ -27,10 +32,11 @@ import { probePort } from "./port-probe.js";
  */
 export interface LocalInstanceResources {
   /**
-   * Instance-specific data root. The first local assistant uses `~` (home
-   * directory) with default ports. Subsequent instances are placed under
-   * `~/.local/share/vellum/assistants/<name>/`.
-   * The daemon's `.vellum/` directory lives inside it.
+   * Instance-specific data root. New local assistants are placed under
+   * `$XDG_DATA_HOME/vellum{-env}/assistants/<name>/`. Legacy entries
+   * (pre env-data-layout) may still point at `~` — the read path honors
+   * whatever `instanceDir` is stored. The daemon's `.vellum/` directory
+   * lives inside it.
    */
   instanceDir: string;
   /** HTTP port for the daemon runtime server */
@@ -84,18 +90,17 @@ export interface AssistantEntry {
   resources?: LocalInstanceResources;
   /** PID of the file watcher process for docker instances hatched with --watch. */
   watcherPid?: number;
-  /** Last-known version of the service group, populated at hatch and updated by health checks. */
-  serviceGroupVersion?: string;
   /** Docker image metadata for rollback. Only present for docker topology entries. */
   containerInfo?: ContainerInfo;
-  /** The service group version that was running before the last upgrade. */
-  previousServiceGroupVersion?: string;
   /** Docker image metadata from before the last upgrade. Enables rollback to the prior version. */
   previousContainerInfo?: ContainerInfo;
   /** Path to the .vbundle backup created for the most recent upgrade. Used by rollback to restore
    *  only the backup from the specific upgrade being rolled back — never a stale backup from a
    *  previous upgrade cycle. */
   preUpgradeBackupPath?: string;
+  /** Running version of the service group at the time of the last upgrade, as reported by
+   *  the health endpoint.  Used by saved-state rollback for logging / broadcast events. */
+  previousVersion?: string;
   /** Pre-upgrade DB migration version — used by rollback to know how far back to revert. */
   previousDbMigrationVersion?: number;
   /** Pre-upgrade workspace migration ID — used by rollback to know how far back to revert. */
@@ -114,15 +119,8 @@ export function getBaseDir(): string {
   return process.env.BASE_DATA_DIR?.trim() || homedir();
 }
 
-/** The lockfile always lives under the home directory. */
-function getLockfileDir(): string {
-  return process.env.VELLUM_LOCKFILE_DIR?.trim() || homedir();
-}
-
 function readLockfile(): LockfileData {
-  const base = getLockfileDir();
-  const candidates = LOCKFILE_NAMES.map((name) => join(base, name));
-  for (const lockfilePath of candidates) {
+  for (const lockfilePath of getLockfilePaths(getCurrentEnvironment())) {
     if (!existsSync(lockfilePath)) continue;
     try {
       const raw = readFileSync(lockfilePath, "utf-8");
@@ -138,7 +136,8 @@ function readLockfile(): LockfileData {
 }
 
 function writeLockfile(data: LockfileData): void {
-  const lockfilePath = join(getLockfileDir(), LOCKFILE_NAMES[0]);
+  const lockfilePath = getLockfilePath(getCurrentEnvironment());
+  mkdirSync(dirname(lockfilePath), { recursive: true });
   const tmpPath = `${lockfilePath}.${randomBytes(4).toString("hex")}.tmp`;
   try {
     writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");
@@ -181,6 +180,13 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
     return false;
   }
 
+  // Apple-containers entries are fully managed by the macOS app.
+  // Skip legacy migration to avoid corrupting their fields.
+  if (raw.cloud === "apple-container") {
+    return false;
+  }
+
+  const env = getCurrentEnvironment();
   let mutated = false;
 
   // Migrate top-level `baseDataDir` → `resources.instanceDir`
@@ -202,11 +208,7 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
     const gatewayPort =
       parsePortFromUrl(raw.runtimeUrl) ?? DEFAULT_GATEWAY_PORT;
     const instanceDir = join(
-      homedir(),
-      ".local",
-      "share",
-      "vellum",
-      "assistants",
+      getMultiInstanceDir(env),
       typeof raw.assistantId === "string"
         ? raw.assistantId
         : DAEMON_INTERNAL_ASSISTANT_ID,
@@ -225,11 +227,7 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
     const res = raw.resources as Record<string, unknown>;
     if (!res.instanceDir) {
       res.instanceDir = join(
-        homedir(),
-        ".local",
-        "share",
-        "vellum",
-        "assistants",
+        getMultiInstanceDir(env),
         typeof raw.assistantId === "string"
           ? raw.assistantId
           : DAEMON_INTERNAL_ASSISTANT_ID,
@@ -388,23 +386,6 @@ export function saveAssistantEntry(entry: AssistantEntry): void {
   writeAssistants(entries);
 }
 
-/**
- * Update just the serviceGroupVersion field on a lockfile entry.
- * Reads the current entry, updates the version if changed, and writes back.
- * No-op if the entry doesn't exist or the version hasn't changed.
- */
-export function updateServiceGroupVersion(
-  assistantId: string,
-  version: string,
-): void {
-  const entries = readAssistants();
-  const entry = entries.find((e) => e.assistantId === assistantId);
-  if (!entry) return;
-  if (entry.serviceGroupVersion === version) return;
-  entry.serviceGroupVersion = version;
-  writeAssistants(entries);
-}
-
 /**
  * Scan upward from `basePort` to find an available port. A port is considered
  * available when `probePort()` returns false (nothing listening). Scans up to
@@ -428,58 +409,32 @@ async function findAvailablePort(
 
 /**
  * Allocate an isolated set of resources for a named local instance.
- * The first local assistant uses the home directory with default ports.
- * Subsequent assistants are placed under
- * `~/.local/share/vellum/assistants/<name>/` with scanned ports.
+ * Every new local assistant is allocated under
+ * `$XDG_DATA_HOME/vellum{-env}/assistants/<name>/`. The legacy `~/.vellum/`
+ * path is only reached via existing lockfile entries from before this change
+ * — the read path honors whatever `resources.instanceDir` is stored, so
+ * production users' existing first-local assistants keep their `~/.vellum/`
+ * roots unchanged.
  */
 export async function allocateLocalResources(
   instanceName: string,
 ): Promise<LocalInstanceResources> {
-  // First local assistant gets the home directory with default ports.
-  // Respect BASE_DATA_DIR when set (e.g. in e2e tests) so the daemon,
-  // gateway, and credential store all resolve paths under the same root.
-  const existingLocals = loadAllAssistants().filter((e) => e.cloud === "local");
-  if (existingLocals.length === 0) {
-    const baseDir = getBaseDir();
-    const vellumDir = join(baseDir, ".vellum");
-    return {
-      instanceDir: baseDir,
-      daemonPort: DEFAULT_DAEMON_PORT,
-      gatewayPort: DEFAULT_GATEWAY_PORT,
-      qdrantPort: DEFAULT_QDRANT_PORT,
-      cesPort: DEFAULT_CES_PORT,
-      pidFile: join(vellumDir, "vellum.pid"),
-    };
-  }
-
-  const instanceDir = join(
-    homedir(),
-    ".local",
-    "share",
-    "vellum",
-    "assistants",
-    instanceName,
-  );
+  const env = getCurrentEnvironment();
+  const instanceDir = join(getMultiInstanceDir(env), instanceName);
   mkdirSync(instanceDir, { recursive: true });
 
   // Collect ports already assigned to other local instances in the lockfile.
-  // Even if those instances are stopped, we must avoid reusing their ports
-  // to prevent binding collisions when both are woken.
   const reservedPorts: number[] = [];
   for (const entry of loadAllAssistants()) {
-    if (entry.cloud !== "local") continue;
-    if (entry.resources) {
-      reservedPorts.push(
-        entry.resources.daemonPort,
-        entry.resources.gatewayPort,
-        entry.resources.qdrantPort,
-        entry.resources.cesPort,
-      );
-    }
+    if (entry.cloud !== "local" || !entry.resources) continue;
+    reservedPorts.push(
+      entry.resources.daemonPort,
+      entry.resources.gatewayPort,
+      entry.resources.qdrantPort,
+      entry.resources.cesPort,
+    );
   }
 
-  // Allocate ports sequentially to avoid overlapping ranges assigning the
-  // same port to multiple services (e.g. daemon 7821-7920 overlaps gateway 7830-7929).
   const daemonPort = await findAvailablePort(
     DEFAULT_DAEMON_PORT,
     reservedPorts,
@@ -510,6 +465,18 @@ export async function allocateLocalResources(
   };
 }
 
+/**
+ * Return `platformBaseUrl` from the lockfile, if set. This is the value
+ * persisted by {@link syncConfigToLockfile} the last time the active
+ * assistant was hatched/waked, and is the source of truth for "which
+ * platform does the currently-active assistant target".
+ */
+export function getLockfilePlatformBaseUrl(): string | undefined {
+  const url = readLockfile().platformBaseUrl;
+  if (typeof url === "string" && url.trim()) return url.trim();
+  return undefined;
+}
+
 /**
  * Read the assistant config file and sync client-relevant values to the
  * lockfile. This lets external tools (e.g. vel) discover the platform URL

package/src/lib/aws.ts

@@ -411,7 +411,18 @@ export async function hatchAws(
       }
     }
 
-    const sshUser = userInfo().username;
+    let sshUser: string;
+    try {
+      sshUser = userInfo().username;
+    } catch {
+      sshUser = process.env.USER ?? "";
+    }
+    if (!sshUser) {
+      console.error(
+        "Error: Could not determine SSH username. Set the USER environment variable and try again.",
+      );
+      process.exit(1);
+    }
     const hatchedBy = process.env.VELLUM_HATCHED_BY;
     const providerApiKeys: Record<string, string> = {};
     for (const [, envVar] of Object.entries(PROVIDER_ENV_VAR_NAMES)) {