@vellumai/cli 0.6.6 → 0.7.1

package/src/lib/assistant-client.ts

@@ -13,9 +13,7 @@
  */
 
 import {
-  findAssistantByName,
-  getActiveAssistant,
-  loadLatestAssistant,
+  resolveAssistant,
 } from "./assistant-config.js";
 import { GATEWAY_PORT } from "./constants.js";
 import { loadGuardianToken } from "./guardian-token.js";
@@ -58,27 +56,13 @@ export class AssistantClient {
    * @throws If no matching assistant is found.
    */
   constructor(opts?: AssistantClientOpts) {
-    const nameOrId = opts?.assistantId;
-    let entry = nameOrId ? findAssistantByName(nameOrId) : null;
-
-    if (nameOrId && !entry) {
-      throw new Error(`No assistant found with name '${nameOrId}'.`);
-    }
-
-    if (!entry) {
-      const active = getActiveAssistant();
-      if (active) {
-        entry = findAssistantByName(active);
-      }
-    }
-
-    if (!entry) {
-      entry = loadLatestAssistant();
-    }
+    const entry = resolveAssistant(opts?.assistantId);
 
     if (!entry) {
       throw new Error(
-        "No assistant found. Hatch one first with 'vellum hatch'.",
+        opts?.assistantId
+          ? `No assistant found with name '${opts.assistantId}'.`
+          : "No assistant found. Hatch one first with 'vellum hatch'.",
       );
     }
 

package/src/lib/assistant-config.ts

@@ -42,8 +42,6 @@ export interface LocalInstanceResources {
   qdrantPort: number;
   /** HTTP port for the CES (Claude Extension Server) */
   cesPort: number;
-  /** Absolute path to the daemon PID file */
-  pidFile: string;
   /** Persisted HMAC signing key (hex). Survives daemon/gateway restarts so
    *  client actor tokens remain valid across `wake` cycles. */
   signingKey?: string;
@@ -114,6 +112,18 @@ export function getBaseDir(): string {
   return process.env.BASE_DATA_DIR?.trim() || homedir();
 }
 
+/**
+ * Derive the daemon PID file path from a resources object. The PID file
+ * lives inside the instance's workspace directory. When no resources are
+ * available, falls back to `~/.vellum/workspace/vellum.pid`.
+ */
+export function getDaemonPidPath(resources?: LocalInstanceResources): string {
+  const vellumDir = resources
+    ? join(resources.instanceDir, ".vellum")
+    : join(homedir(), ".vellum");
+  return join(vellumDir, "workspace", "vellum.pid");
+}
+
 function readLockfile(): LockfileData {
   for (const lockfilePath of getLockfilePaths(getCurrentEnvironment())) {
     if (!existsSync(lockfilePath)) continue;
@@ -215,7 +225,6 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
       gatewayPort,
       qdrantPort: defaultPorts.qdrant,
       cesPort: defaultPorts.ces,
-      pidFile: join(instanceDir, ".vellum", "vellum.pid"),
     };
     mutated = true;
   } else {
@@ -247,10 +256,6 @@ export function migrateLegacyEntry(raw: Record<string, unknown>): boolean {
       res.cesPort = defaultPorts.ces;
       mutated = true;
     }
-    if (typeof res.pidFile !== "string") {
-      res.pidFile = join(res.instanceDir as string, ".vellum", "vellum.pid");
-      mutated = true;
-    }
   }
 
   return mutated;
@@ -338,19 +343,17 @@ export function setActiveAssistant(assistantId: string): void {
 }
 
 /**
- * Resolve which assistant to target for a command. Priority:
+ * Best-effort resolution of the target assistant. Returns null when no
+ * match is found — callers decide how to handle the absence.
+ *
+ * Priority:
  * 1. Explicit name argument
  * 2. Active assistant set via `vellum use`
- * 3. Sole local assistant (when exactly one exists)
+ * 3. Sole lockfile entry (any cloud)
  */
-export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
+export function resolveAssistant(nameArg?: string): AssistantEntry | null {
   if (nameArg) {
-    const entry = findAssistantByName(nameArg);
-    if (!entry) {
-      console.error(`No assistant found with name '${nameArg}'.`);
-      process.exit(1);
-    }
-    return entry;
+    return findAssistantByName(nameArg);
   }
 
   const active = getActiveAssistant();
@@ -361,15 +364,35 @@ export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
   }
 
   const all = readAssistants();
-  const locals = all.filter((e) => e.cloud === "local");
-  if (locals.length === 1) return locals[0];
+  if (all.length === 1) return all[0];
 
-  if (locals.length === 0) {
-    console.error("No local assistant found. Run 'vellum hatch local' first.");
+  return null;
+}
+
+/**
+ * Resolve which assistant to target for a command, exiting the process
+ * with a user-facing error when resolution fails.
+ *
+ * Priority:
+ * 1. Explicit name argument
+ * 2. Active assistant set via `vellum use`
+ * 3. Sole lockfile entry (any cloud)
+ */
+export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
+  const entry = resolveAssistant(nameArg);
+  if (entry) return entry;
+
+  if (nameArg) {
+    console.error(`No assistant found with name '${nameArg}'.`);
   } else {
-    console.error(
-      `Multiple assistants found. Set an active assistant with 'vellum use <name>'.`,
-    );
+    const all = readAssistants();
+    if (all.length === 0) {
+      console.error("No assistant found. Run 'vellum hatch' first.");
+    } else {
+      console.error(
+        `Multiple assistants found. Set an active assistant with 'vellum use <name>'.`,
+      );
+    }
   }
   process.exit(1);
 }
@@ -474,7 +497,6 @@ export async function allocateLocalResources(
     gatewayPort,
     qdrantPort,
     cesPort,
-    pidFile: join(instanceDir, ".vellum", "vellum.pid"),
   };
 }
 

package/src/lib/cli-error.ts

@@ -9,6 +9,7 @@
 
 /** Known error categories emitted by CLI commands. */
 export type CliErrorCategory =
+  | "CLI_UPDATE_FAILED"
   | "DOCKER_NOT_RUNNING"
   | "IMAGE_PULL_FAILED"
   | "MISSING_VERSION"

package/src/lib/client-identity.ts

@@ -0,0 +1,67 @@
+/**
+ * Stable per-install client identity for the CLI.
+ *
+ * Generates a UUID on first use and persists it to
+ * `~/.config/vellum/client-id` so the daemon's event hub can
+ * track this terminal across SSE reconnects and CLI restarts.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { randomUUID } from "crypto";
+import { homedir } from "os";
+import { join } from "path";
+
+const CLI_INTERFACE_ID = "cli";
+
+let cached: string | null = null;
+
+function getConfigDir(): string {
+  const configHome = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(configHome, "vellum");
+}
+
+/**
+ * Returns a stable UUID identifying this CLI installation.
+ * Generated once and persisted to `~/.config/vellum/client-id`.
+ */
+export function getClientId(): string {
+  if (cached) return cached;
+
+  const configDir = getConfigDir();
+  const idFile = join(configDir, "client-id");
+
+  try {
+    if (existsSync(idFile)) {
+      const stored = readFileSync(idFile, "utf-8").trim();
+      if (stored) {
+        cached = stored;
+        return stored;
+      }
+    }
+  } catch {
+    /* best-effort read */
+  }
+
+  const id = randomUUID();
+  try {
+    mkdirSync(configDir, { recursive: true });
+    writeFileSync(idFile, id, "utf-8");
+  } catch {
+    /* best-effort persist — transient id still works for this session */
+  }
+
+  cached = id;
+  return id;
+}
+
+/**
+ * Headers that identify this CLI client to the assistant daemon.
+ * Attach to SSE streaming connections so the ClientRegistry can
+ * track connected clients and their capabilities.
+ */
+export function getClientRegistrationHeaders(): Record<string, string> {
+  return {
+    "X-Vellum-Client-Id": getClientId(),
+    "X-Vellum-Interface-Id": CLI_INTERFACE_ID,
+  };
+}

package/src/lib/docker.ts

@@ -6,13 +6,6 @@ import { dirname, join } from "path";
 // Direct import — bun embeds this at compile time so it works in compiled binaries.
 import cliPkg from "../../package.json";
 
-// Pulled from skills/ — the Meet avatar device-path default is owned by the
-// meet-join skill; importing here keeps the CLI's Docker wiring locked to the
-// same value the bot and config schema use. The shared module is deliberately
-// zero-dep so this import cannot drag unrelated surface into the compiled CLI
-// binary.
-import { AVATAR_DEVICE_PATH_DEFAULT } from "../../../skills/meet-join/shared/avatar-device-path.js";
-
 import {
   findAssistantByName,
   saveAssistantEntry,
@@ -53,62 +46,24 @@ export const GATEWAY_INTERNAL_PORT = 7830;
 /** Max time to wait for the assistant container to emit the readiness sentinel. */
 export const DOCKER_READY_TIMEOUT_MS = 3 * 60 * 1000;
 
-/**
- * Default virtual-camera device path when the Meet avatar feature is
- * enabled. Re-exports the shared
- * {@link ../../../skills/meet-join/shared/avatar-device-path.js AVATAR_DEVICE_PATH_DEFAULT}
- * so the CLI's device-passthrough wiring cannot drift from the bot's
- * Chrome-flag wiring or the workspace config default. Matches the
- * `video_nr=10` value in the README's host-setup section
- * (`skills/meet-join/bot/README.md`). Operators can override the path by
- * setting `VELLUM_MEET_AVATAR_DEVICE` to something other than the default
- * (e.g. `/dev/video11` if a different `video_nr` was used).
- */
-export const DEFAULT_MEET_AVATAR_DEVICE_PATH = AVATAR_DEVICE_PATH_DEFAULT;
-
-/**
- * Env-var opt-in for bind-mounting the v4l2loopback virtual-camera device
- * into the assistant container. Set to a truthy value (`1`, `true`, `yes`)
- * to enable; unset or falsy disables the passthrough entirely.
- *
- * Kept as an env-var rather than a config-schema field because the Meet
- * avatar config schema lands in a later PR (PR 5 of the phase-4 plan) —
- * threading the config through the CLI's boot flow now would force a
- * forward dependency. Once the schema lands, the CLI can either keep this
- * env-var as a pre-config override or move the opt-in into the workspace
- * config.
- */
-export const MEET_AVATAR_ENV_VAR = "VELLUM_MEET_AVATAR";
+/** Default virtual-camera device path. Overridable via `VELLUM_AVATAR_DEVICE`. */
+const DEFAULT_AVATAR_DEVICE_PATH = "/dev/video10";
 
-/**
- * Override for the virtual-camera device path. Defaults to
- * {@link DEFAULT_MEET_AVATAR_DEVICE_PATH}.
- */
-export const MEET_AVATAR_DEVICE_ENV_VAR = "VELLUM_MEET_AVATAR_DEVICE";
+/** Env var the assistant reads to discover its virtual-camera device path. */
+export const AVATAR_DEVICE_ENV_VAR = "VELLUM_AVATAR_DEVICE";
 
 /**
- * Resolve the Meet avatar device path to pass through to the assistant
- * container, or `null` if the feature is not opted into. Exported so tests
- * can assert against the env-var parsing without reaching into the shell.
+ * Resolve the avatar device path from the environment. Always returns a
+ * value — the CLI unconditionally passes the device path to the assistant
+ * container; the skill decides whether to use it.
  */
-export function resolveMeetAvatarDevicePath(
+export function resolveAvatarDevicePath(
   env: NodeJS.ProcessEnv = process.env,
-): string | null {
-  const flag = env[MEET_AVATAR_ENV_VAR];
-  if (!flag) return null;
-  const normalized = flag.trim().toLowerCase();
-  if (
-    normalized === "" ||
-    normalized === "0" ||
-    normalized === "false" ||
-    normalized === "no"
-  ) {
-    return null;
-  }
-  const override = env[MEET_AVATAR_DEVICE_ENV_VAR];
+): string {
+  const override = env[AVATAR_DEVICE_ENV_VAR];
   return override && override.length > 0
     ? override
-    : DEFAULT_MEET_AVATAR_DEVICE_PATH;
+    : DEFAULT_AVATAR_DEVICE_PATH;
 }
 
 /** Default memory (GiB) allocated to the Colima VM. */
@@ -405,10 +360,12 @@ async function ensureDockerInstalled(): Promise<void> {
 export function dockerResourceNames(instanceName: string) {
   return {
     assistantContainer: `${instanceName}-assistant`,
+    assistantIpcVolume: `${instanceName}-assistant-ipc`,
     cesContainer: `${instanceName}-credential-executor`,
     cesSecurityVolume: `${instanceName}-ces-sec`,
     dockerdDataVolume: `${instanceName}-dockerd-data`,
     gatewayContainer: `${instanceName}-gateway`,
+    gatewayIpcVolume: `${instanceName}-gateway-ipc`,
     gatewaySecurityVolume: `${instanceName}-gateway-sec`,
     network: `${instanceName}-net`,
     socketVolume: `${instanceName}-socket`,
@@ -464,6 +421,8 @@ export async function retireDocker(name: string): Promise<void> {
   }
   for (const vol of [
     res.socketVolume,
+    res.assistantIpcVolume,
+    res.gatewayIpcVolume,
     res.workspaceVolume,
     res.cesSecurityVolume,
     res.gatewaySecurityVolume,
@@ -635,8 +594,19 @@ export function serviceDockerRunArgs(opts: {
       // container runs its own `dockerd` so the Meet subsystem can spawn
       // sibling meet-bot containers without needing access to the host's
       // Docker engine. This requires:
-      //   - `--privileged` so the inner dockerd can manage cgroups, iptables,
-      //     overlayfs mounts, etc.
+      //   - `CAP_SYS_ADMIN` + `CAP_NET_ADMIN` so the inner dockerd can
+      //     configure cgroups, overlay mounts, network namespaces, and
+      //     iptables. We deliberately avoid `--privileged` (which grants the
+      //     full host capability set and access to every host device node)
+      //     to shrink the escape surface from any code running inside the
+      //     assistant container. See the "Security tradeoff for Docker mode"
+      //     note in AGENTS.md.
+      //   - `seccomp=unconfined` + `apparmor=unconfined` because Docker's
+      //     default seccomp profile blocks syscalls dockerd needs (e.g.
+      //     certain clone/unshare and pivot_root flags) and the default
+      //     AppArmor profile on Debian/Ubuntu hosts denies the mount
+      //     operations dockerd performs while launching bot containers. On
+      //     hosts where these LSMs are inactive, the options are no-ops.
       //   - A dedicated named volume mounted at `/var/lib/docker` so the
       //     inner Docker image cache and container state survive restarts of
       //     the assistant container.
@@ -646,7 +616,14 @@ export function serviceDockerRunArgs(opts: {
         "run",
         "--init",
         "-d",
-        "--privileged",
+        "--cap-add",
+        "SYS_ADMIN",
+        "--cap-add",
+        "NET_ADMIN",
+        "--security-opt",
+        "seccomp=unconfined",
+        "--security-opt",
+        "apparmor=unconfined",
         "--name",
         res.assistantContainer,
         `--network=${res.network}`,
@@ -677,10 +654,16 @@ export function serviceDockerRunArgs(opts: {
         "-v",
         `${res.socketVolume}:/run/ces-bootstrap`,
         "-v",
+        `${res.assistantIpcVolume}:/run/assistant-ipc`,
+        "-v",
+        `${res.gatewayIpcVolume}:/run/gateway-ipc`,
+        "-v",
         `${res.dockerdDataVolume}:/var/lib/docker`,
         "-e",
         "IS_CONTAINERIZED=true",
         "-e",
+        "DEBUG_STDOUT_LOGS=1",
+        "-e",
         `VELLUM_ASSISTANT_NAME=${instanceName}`,
         "-e",
         "VELLUM_CLOUD=docker",
@@ -696,6 +679,10 @@ export function serviceDockerRunArgs(opts: {
         "CES_CREDENTIAL_URL=http://localhost:8090",
         "-e",
         `GATEWAY_INTERNAL_URL=http://localhost:${GATEWAY_INTERNAL_PORT}`,
+        "-e",
+        "GATEWAY_IPC_SOCKET_DIR=/run/gateway-ipc",
+        "-e",
+        "ASSISTANT_IPC_SOCKET_DIR=/run/assistant-ipc",
       ];
       if (defaultWorkspaceConfigPath) {
         const containerPath = `/tmp/vellum-default-workspace-config-${Date.now()}.json`;
@@ -712,6 +699,14 @@ export function serviceDockerRunArgs(opts: {
       if (opts.signingKey) {
         args.push("-e", `ACTOR_TOKEN_SIGNING_KEY=${opts.signingKey}`);
       }
+      if (opts.bootstrapSecret) {
+        // Mirror the secret into the assistant container so the runtime's
+        // guardian-bootstrap handler can validate the x-bootstrap-secret
+        // header forwarded by the gateway. Without this, the published
+        // runtime port would expose an unauthenticated token-minting
+        // endpoint reachable from the host bypassing the gateway's gate.
+        args.push("-e", `GUARDIAN_BOOTSTRAP_SECRET=${opts.bootstrapSecret}`);
+      }
       for (const envVar of [
         ...Object.values(PROVIDER_ENV_VAR_NAMES),
         "VELLUM_ENVIRONMENT",
@@ -726,22 +721,13 @@ export function serviceDockerRunArgs(opts: {
           args.push("-e", `${key}=${value}`);
         }
       }
-      // Optional Meet avatar (v4l2loopback) passthrough. When
-      // `VELLUM_MEET_AVATAR=1` is set in the caller's environment, bind the
-      // virtual-camera device node (default `/dev/video10`) into the
-      // assistant container so the nested `dockerd` can in turn pass it
-      // through to the Meet-bot container. The daemon-side equivalent of
-      // this opt-in lives on `DockerRunner.run()`'s `avatarDevicePath`
-      // option (see `skills/meet-join/daemon/docker-runner.ts`).
-      const avatarDevice = resolveMeetAvatarDevicePath();
-      if (avatarDevice) {
+      const avatarDevice = resolveAvatarDevicePath();
+      if (existsSync(avatarDevice)) {
         args.push(
           "--device",
           `${avatarDevice}:${avatarDevice}`,
           "-e",
-          `${MEET_AVATAR_ENV_VAR}=1`,
-          "-e",
-          `${MEET_AVATAR_DEVICE_ENV_VAR}=${avatarDevice}`,
+          `${AVATAR_DEVICE_ENV_VAR}=${avatarDevice}`,
         );
       }
       args.push(imageTags.assistant);
@@ -758,6 +744,10 @@ export function serviceDockerRunArgs(opts: {
       `${res.workspaceVolume}:/workspace`,
       "-v",
       `${res.gatewaySecurityVolume}:/gateway-security`,
+      "-v",
+      `${res.assistantIpcVolume}:/run/assistant-ipc`,
+      "-v",
+      `${res.gatewayIpcVolume}:/run/gateway-ipc`,
       "-e",
       "VELLUM_WORKSPACE_DIR=/workspace",
       "-e",
@@ -769,9 +759,11 @@ export function serviceDockerRunArgs(opts: {
       "-e",
       `RUNTIME_HTTP_PORT=${ASSISTANT_INTERNAL_PORT}`,
       "-e",
-      "RUNTIME_PROXY_ENABLED=true",
-      "-e",
       "CES_CREDENTIAL_URL=http://localhost:8090",
+      "-e",
+      "GATEWAY_IPC_SOCKET_DIR=/run/gateway-ipc",
+      "-e",
+      "ASSISTANT_IPC_SOCKET_DIR=/run/assistant-ipc",
       ...(cesServiceToken
         ? ["-e", `CES_SERVICE_TOKEN=${cesServiceToken}`]
         : []),
@@ -1257,21 +1249,27 @@ export async function hatchDocker(
     log("📁 Creating network and volumes...");
     await exec("docker", ["network", "create", res.network]);
     await exec("docker", ["volume", "create", res.socketVolume]);
+    await exec("docker", ["volume", "create", res.assistantIpcVolume]);
+    await exec("docker", ["volume", "create", res.gatewayIpcVolume]);
     await exec("docker", ["volume", "create", res.workspaceVolume]);
     await exec("docker", ["volume", "create", res.cesSecurityVolume]);
     await exec("docker", ["volume", "create", res.gatewaySecurityVolume]);
     await exec("docker", ["volume", "create", res.dockerdDataVolume]);
 
-    // Set workspace volume ownership so non-root containers (UID 1001) can write.
+    // Set volume ownership so non-root containers (UID 1001) can write.
     await exec("docker", [
       "run",
       "--rm",
       "-v",
       `${res.workspaceVolume}:/workspace`,
+      "-v",
+      `${res.assistantIpcVolume}:/run/assistant-ipc`,
+      "-v",
+      `${res.gatewayIpcVolume}:/run/gateway-ipc`,
       "busybox",
-      "chown",
-      "1001:1001",
-      "/workspace",
+      "sh",
+      "-c",
+      "chown 1001:1001 /workspace /run/assistant-ipc /run/gateway-ipc",
     ]);
 
     // Write --config key=value pairs to a temp file that gets bind-mounted

package/src/lib/environments/__tests__/paths.test.ts

@@ -32,11 +32,13 @@ type EnvironmentDefinition = import("../types.js").EnvironmentDefinition;
 const prod: EnvironmentDefinition = {
   name: "production",
   platformUrl: "https://platform.vellum.ai",
+  webUrl: "https://www.vellum.ai",
 };
 
 const dev: EnvironmentDefinition = {
   name: "dev",
   platformUrl: "https://dev-platform.vellum.ai",
+  webUrl: "https://dev-assistant.vellum.ai",
 };
 
 const XDG_ENV_VARS = ["XDG_DATA_HOME", "XDG_CONFIG_HOME"] as const;

package/src/lib/environments/resolve.ts

@@ -1,8 +1,65 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
 import { SEEDS } from "./seeds.js";
 import type { EnvironmentDefinition } from "./types.js";
 
 const DEFAULT_ENVIRONMENT_NAME = "production";
 
+/**
+ * Path to the user's persisted default environment file.
+ * Lives at `~/.config/vellum/environment` — a fixed, environment-agnostic
+ * location so it can be read before the environment is resolved.
+ */
+function getDefaultEnvironmentPath(): string {
+  const xdgConfig =
+    process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
+  return join(xdgConfig, "vellum", "environment");
+}
+
+/**
+ * Read the persisted default environment name, if any.
+ * Returns `undefined` if no file exists or the file is empty.
+ */
+export function readDefaultEnvironment(): string | undefined {
+  const filePath = getDefaultEnvironmentPath();
+  try {
+    if (!existsSync(filePath)) return undefined;
+    const content = readFileSync(filePath, "utf-8").trim();
+    return content.length > 0 ? content : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Persist a default environment name to the user config file.
+ */
+export function writeDefaultEnvironment(name: string): void {
+  const filePath = getDefaultEnvironmentPath();
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, name + "\n", "utf-8");
+}
+
+/**
+ * Remove the persisted default environment file, falling back to production.
+ */
+export function clearDefaultEnvironment(): void {
+  const filePath = getDefaultEnvironmentPath();
+  try {
+    unlinkSync(filePath);
+  } catch {
+    // Already absent — nothing to do.
+  }
+}
+
 /**
  * Look up a seed entry by name. Returns `undefined` if no seed matches.
  * Callers that need the full resolution stack (env-var overrides, default
@@ -22,12 +79,13 @@ export function getSeed(name: string): EnvironmentDefinition | undefined {
  * Priority:
  *   1. `override` argument (from a `--environment` CLI flag, when wired)
  *   2. `VELLUM_ENVIRONMENT` env var
- *   3. (future) user context file
+ *   3. User config file (`~/.config/vellum/environment`, set via `vellum env set`)
  *   4. Default: `production`
  *
  * Per-field env-var overrides are honored on the resolved definition as
  * ad-hoc escape hatches (they do not materialize new environments):
  *   - `VELLUM_PLATFORM_URL` overrides `platformUrl`
+ *   - `VELLUM_WEB_URL` overrides `webUrl`
  *   - `VELLUM_ASSISTANT_PLATFORM_URL` overrides `assistantPlatformUrl`
  *   - `VELLUM_LOCKFILE_DIR` overrides `lockfileDirOverride` (legacy e2e
  *     test hook)
@@ -38,7 +96,15 @@ export function getSeed(name: string): EnvironmentDefinition | undefined {
 export function getCurrentEnvironment(
   override?: string,
 ): EnvironmentDefinition {
-  const name = resolveEnvironmentName(override);
+  const { name, source } = resolveEnvironmentSource(override);
+
+  // When the environment was resolved from the config file, propagate it
+  // into process.env so child processes (daemon, gateway) inherit the same
+  // environment without needing to read the config file themselves.
+  if (source === "config" && !process.env.VELLUM_ENVIRONMENT) {
+    process.env.VELLUM_ENVIRONMENT = name;
+  }
+
   const seed = SEEDS[name];
   if (!seed) {
     if (name !== DEFAULT_ENVIRONMENT_NAME) {
@@ -68,6 +134,11 @@ export function getCurrentEnvironment(
     resolved.platformUrl = platformUrlOverride;
   }
 
+  const webUrlOverride = process.env.VELLUM_WEB_URL?.trim();
+  if (webUrlOverride) {
+    resolved.webUrl = webUrlOverride;
+  }
+
   const assistantPlatformUrlOverride =
     process.env.VELLUM_ASSISTANT_PLATFORM_URL?.trim();
   if (assistantPlatformUrlOverride) {
@@ -82,15 +153,26 @@ export function getCurrentEnvironment(
   return resolved;
 }
 
-function resolveEnvironmentName(override: string | undefined): string {
+/**
+ * Resolve the environment name and its source for diagnostics.
+ */
+export function resolveEnvironmentSource(override?: string): {
+  name: string;
+  source: "flag" | "env" | "config" | "default";
+} {
   const trimmedOverride = override?.trim();
   if (trimmedOverride && trimmedOverride.length > 0) {
-    return trimmedOverride;
+    return { name: trimmedOverride, source: "flag" };
   }
   const envVar = process.env.VELLUM_ENVIRONMENT?.trim();
   if (envVar && envVar.length > 0) {
-    return envVar;
+    return { name: envVar, source: "env" };
   }
-
-  return DEFAULT_ENVIRONMENT_NAME;
+  const configDefault = readDefaultEnvironment();
+  if (configDefault) {
+    return { name: configDefault, source: "config" };
+  }
+  return { name: DEFAULT_ENVIRONMENT_NAME, source: "default" };
 }
+
+