@vellumai/cli 0.6.6 → 0.7.0

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;
+/** Default virtual-camera device path. Overridable via `VELLUM_AVATAR_DEVICE`. */
+const DEFAULT_AVATAR_DEVICE_PATH = "/dev/video10";
 
-/**
- * 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";
+/** Env var the assistant reads to discover its virtual-camera device path. */
+export const AVATAR_DEVICE_ENV_VAR = "VELLUM_AVATAR_DEVICE";
 
 /**
- * Override for the virtual-camera device path. Defaults to
- * {@link DEFAULT_MEET_AVATAR_DEVICE_PATH}.
+ * 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 const MEET_AVATAR_DEVICE_ENV_VAR = "VELLUM_MEET_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.
- */
-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,6 +654,10 @@ 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",
@@ -696,6 +677,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 +697,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 +719,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 +742,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",
@@ -772,6 +760,10 @@ export function serviceDockerRunArgs(opts: {
       "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" };
 }
+
+

package/src/lib/environments/seeds.ts

@@ -28,13 +28,11 @@ function portBlock(base: number): PortMap {
  * Built-in environment definitions. Mirrors Swift's
  * `clients/macos/vellum-assistant/App/VellumEnvironment.swift` enum and is
  * the TS-side source of truth for the set of known environment names.
- * Two other TS sites duplicate the name list:
+ * One other TS site duplicates the name list:
  *   - `assistant/src/util/platform.ts` (`KNOWN_ENVIRONMENTS`)
- *   - `clients/chrome-extension/native-host/src/lockfile.ts`
- *     (`NON_PRODUCTION_ENVIRONMENTS`, excludes `production`)
- * Drift between these three sites is caught at test time by
+ * Drift between these two sites is caught at test time by
  * `cli/src/__tests__/env-drift.test.ts`. Fast follow: hoist the shared
- * list into a `packages/environments` package so all three sites import
+ * list into a `packages/environments` package so both sites import
  * from one place.
  *
  * Custom environments via a user config file are a future phase — see the
@@ -45,10 +43,12 @@ export const SEEDS: Record<string, EnvironmentDefinition> = {
   production: {
     name: "production",
     platformUrl: "https://platform.vellum.ai",
+    webUrl: "https://www.vellum.ai",
   },
   staging: {
     name: "staging",
     platformUrl: "https://staging-platform.vellum.ai",
+    webUrl: "https://staging-assistant.vellum.ai",
     portsOverride: portBlock(17000),
   },
   test: {
@@ -56,16 +56,19 @@ export const SEEDS: Record<string, EnvironmentDefinition> = {
     // Non-functional URL — used only by unit tests for URL resolution, never
     // hit in production.
     platformUrl: "https://test-platform.vellum.ai",
+    webUrl: "https://dev-assistant.vellum.ai",
     portsOverride: portBlock(19000),
   },
   dev: {
     name: "dev",
     platformUrl: "https://dev-platform.vellum.ai",
+    webUrl: "https://dev-assistant.vellum.ai",
     portsOverride: portBlock(18000),
   },
   local: {
     name: "local",
     platformUrl: "http://localhost:8000",
+    webUrl: "http://localhost:3000",
     // assistantPlatformUrl: "http://host.docker.internal:8000",
     // ^ uncomment this once dockerized hatch path is live.
     // The assistant runs in a different network namespace than the host.

package/src/lib/environments/types.ts

@@ -30,6 +30,16 @@ export interface EnvironmentDefinition {
   name: string;
   platformUrl: string;
 
+  /**
+   * The web app (Next.js) base URL for browser-facing pages like
+   * `/account/login`. In production this is separate from the API backend
+   * (e.g. `www.vellum.ai` vs `platform.vellum.ai`); locally it's
+   * `localhost:3000` vs `localhost:8000`.
+   *
+   * Mirrors `VellumEnvironment.webURL` on the Swift side.
+   */
+  webUrl: string;
+
   /**
    * Override for the platform URL the assistant process itself uses. Only
    * differs from `platformUrl` when the assistant runs in a different network