@vellumai/cli 0.8.8-dev.202606081859.f7bdc00 → 0.8.8-dev.202606082058.447e3b6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.8.8-dev.202606081859.f7bdc00",
+  "version": "0.8.8-dev.202606082058.447e3b6",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/assistant-client-refresh.test.ts

@@ -25,7 +25,7 @@ import { AssistantClient } from "../lib/assistant-client.js";
 import { saveAssistantEntry } from "../lib/assistant-config.js";
 import { loadGuardianToken, saveGuardianToken } from "../lib/guardian-token.js";
 
-const RUNTIME = "http://10.0.0.9:7830";
+const RUNTIME = "https://gw.example.com";
 const FUTURE = new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString();
 
 function seedPaired(refreshToken: string): void {

package/src/__tests__/client-tui-refresh.test.ts

@@ -17,7 +17,7 @@ import { resolveFreshBearerToken } from "../commands/client.js";
 import { saveAssistantEntry } from "../lib/assistant-config.js";
 import { saveGuardianToken } from "../lib/guardian-token.js";
 
-const RUNTIME = "http://10.0.0.9:7830";
+const RUNTIME = "https://gw.example.com";
 const past = () => new Date(Date.now() - 60_000).toISOString();
 const future = () => new Date(Date.now() + 60 * 60 * 1000).toISOString();
 

package/src/__tests__/guardian-token.test.ts

@@ -293,7 +293,7 @@ describe("refreshGuardianToken", () => {
       );
     }) as typeof fetch;
 
-    const result = await refreshGuardianToken("http://10.0.0.9:7830", "px");
+    const result = await refreshGuardianToken("https://gw.example.com", "px");
 
     expect(result?.accessToken).toBe("new-acc");
     expect(loadGuardianToken("px")?.accessToken).toBe("new-acc");
@@ -309,7 +309,9 @@ describe("refreshGuardianToken", () => {
       return new Response("", { status: 200 });
     }) as typeof fetch;
 
-    expect(await refreshGuardianToken("http://10.0.0.9:7830", "px")).toBeNull();
+    expect(
+      await refreshGuardianToken("https://gw.example.com", "px"),
+    ).toBeNull();
     expect(called).toBe(false);
   });
 
@@ -321,7 +323,7 @@ describe("refreshGuardianToken", () => {
     }) as typeof fetch;
 
     expect(
-      await refreshGuardianToken("http://10.0.0.9:7830", "missing"),
+      await refreshGuardianToken("https://gw.example.com", "missing"),
     ).toBeNull();
     expect(called).toBe(false);
   });
@@ -342,8 +344,75 @@ describe("refreshGuardianToken", () => {
         headers: { "content-type": "application/json" },
       })) as typeof fetch;
 
-    const result = await refreshGuardianToken("http://10.0.0.9:7830", "px");
+    const result = await refreshGuardianToken("https://gw.example.com", "px");
     expect(result?.accessToken).toBe("new-acc");
     expect(existsSync(lp)).toBe(false); // stolen lock cleaned up after release
   });
+
+  // The refresh token is long-lived and replayable, so it must only travel over
+  // a confidential channel: https, or a loopback host. These guard the
+  // plaintext-interception vector flagged in the security review.
+
+  test("sends the refresh token over loopback http (127.0.0.1 / localhost / [::1])", async () => {
+    for (const url of [
+      "http://127.0.0.1:7830",
+      "http://localhost:7830",
+      "http://[::1]:7830",
+    ]) {
+      seed(future());
+      let called = false;
+      globalThis.fetch = (async (_url: unknown, _init?: RequestInit) => {
+        called = true;
+        return new Response(JSON.stringify({ accessToken: "new-acc" }), {
+          status: 200,
+          headers: { "content-type": "application/json" },
+        });
+      }) as typeof fetch;
+
+      expect(await refreshGuardianToken(url, "px")).not.toBeNull();
+      expect(called).toBe(true); // loopback http is allowed
+    }
+  });
+
+  test("refuses a non-loopback plaintext http URL: no fetch, returns null, warns", async () => {
+    seed(future());
+    let called = false;
+    globalThis.fetch = (async (_url: unknown, _init?: RequestInit) => {
+      called = true;
+      return new Response("", { status: 200 });
+    }) as typeof fetch;
+
+    const origWarn = console.warn;
+    let warned = false;
+    console.warn = () => {
+      warned = true;
+    };
+    try {
+      expect(
+        await refreshGuardianToken("http://10.0.0.5:7830", "px"),
+      ).toBeNull();
+    } finally {
+      console.warn = origWarn;
+    }
+    expect(called).toBe(false); // the refresh token is never sent
+    expect(warned).toBe(true);
+  });
+
+  test("refuses a malformed gateway URL: no fetch, returns null", async () => {
+    seed(future());
+    let called = false;
+    globalThis.fetch = (async (_url: unknown, _init?: RequestInit) => {
+      called = true;
+      return new Response("", { status: 200 });
+    }) as typeof fetch;
+
+    const origWarn = console.warn;
+    console.warn = () => {};
+    try {
+      expect(await refreshGuardianToken("not-a-url", "px")).toBeNull();
+    } finally {
+      console.warn = origWarn;
+    }
+    expect(called).toBe(false);
+  });
 });

package/src/__tests__/teleport.test.ts

@@ -779,6 +779,7 @@ describe("resolveOrHatchTarget", () => {
       "new-one",
       false,
       {},
+      {},
       { setupProviderCredentials: false },
     );
     expect(result).toBe(newEntry);

package/src/__tests__/tui-midsession-refresh.test.ts

@@ -18,7 +18,7 @@ import { maybeRefreshAuthHeaders } from "../components/DefaultMainScreen";
 import { saveAssistantEntry } from "../lib/assistant-config";
 import { saveGuardianToken } from "../lib/guardian-token";
 
-const RUNTIME = "http://10.0.0.9:7830";
+const RUNTIME = "https://gw.example.com";
 const future = () => new Date(Date.now() + 60 * 60 * 1000).toISOString();
 
 function seedEntry(cloud: string, localUrl?: string): void {

package/src/commands/client.ts

@@ -43,6 +43,7 @@ import {
   type CliInvocation,
 } from "@vellumai/local-mode";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+import { parseFeatureFlagArgs, readAmbientFlagEnvVars } from "../lib/flag-args";
 import {
   fetchOrganizationId,
   fetchPlatformAssistants,
@@ -76,6 +77,10 @@ interface ParsedArgs {
   bearerToken?: string;
   /** Interface identifier sent as X-Vellum-Interface-Id on all requests. */
   interfaceId: SupportedInterface;
+  /** VELLUM_FLAG_* env vars for the gateway (process.env propagation). */
+  flagEnvVars: Record<string, string>;
+  /** Parsed --flag overrides: kebab-case key -> typed value (for web injection). */
+  parsedFlagOverrides: Record<string, boolean | string>;
 }
 
 function readAssistantName(entry: AssistantEntry | null): string | undefined {
@@ -87,7 +92,26 @@ function readAssistantName(entry: AssistantEntry | null): string | undefined {
 
 // Exported for unit testing the arg/auth resolution without launching the TUI.
 export function parseArgs(): ParsedArgs {
-  const args = process.argv.slice(3);
+  const { envVars: cliFlagVars, remaining: argsWithoutFlags } =
+    parseFeatureFlagArgs(process.argv.slice(3));
+  const flagEnvVars = { ...readAmbientFlagEnvVars(), ...cliFlagVars };
+  const args = argsWithoutFlags;
+
+  // Build parsedFlagOverrides from the extracted env vars:
+  // VELLUM_FLAG_UPPER_SNAKE -> kebab-case key with typed value.
+  const parsedFlagOverrides: Record<string, boolean | string> = {};
+  for (const [envName, rawValue] of Object.entries(flagEnvVars)) {
+    const snake = envName.replace(/^VELLUM_FLAG_/, "");
+    const kebab = snake.toLowerCase().replace(/_/g, "-");
+    const lower = rawValue.toLowerCase();
+    if (["true", "1", "yes", "on"].includes(lower)) {
+      parsedFlagOverrides[kebab] = true;
+    } else if (["false", "0", "no", "off"].includes(lower)) {
+      parsedFlagOverrides[kebab] = false;
+    } else {
+      parsedFlagOverrides[kebab] = rawValue;
+    }
+  }
 
   const positionalName = parseAssistantTargetArg(args, [
     "--url",
@@ -222,6 +246,8 @@ export function parseArgs(): ParsedArgs {
     platformToken,
     bearerToken,
     interfaceId,
+    flagEnvVars,
+    parsedFlagOverrides,
   };
 }
 
@@ -241,6 +267,7 @@ ${ANSI.bold}OPTIONS:${ANSI.reset}
                               not persisted.
     -a, --assistant-id <id>    Assistant ID
     -i, --interface <id>       Interface identifier: cli (default) or web
+    --flag <key=value>         Feature flag override (repeatable, kebab-case key)
     -h, --help                 Show this help message
 
 ${ANSI.bold}DEFAULTS:${ANSI.reset}
@@ -250,12 +277,14 @@ ${ANSI.bold}DEFAULTS:${ANSI.reset}
 ${ANSI.bold}EXAMPLES:${ANSI.reset}
     vellum client
     vellum client vellum-assistant-foo
-    vellum client --url http://34.56.78.90:${GATEWAY_PORT}
+    # Remote assistants must be reached over https (e.g. a tunnel) — the
+    # guardian refresh token is only sent over https or a loopback address:
+    vellum client --url https://your-tunnel.example
     vellum client vellum-assistant-foo --url http://localhost:${GATEWAY_PORT}
 
     # Ephemeral: connect to another machine's assistant with a paired token
     # (no lockfile entry, nothing persisted):
-    vellum client --url http://10.0.0.196:${GATEWAY_PORT} --token <jwt>
+    vellum client --url https://your-tunnel.example --token <jwt>
 `);
 }
 
@@ -616,12 +645,18 @@ function getBaseDir(): string {
   return path.resolve(import.meta.dir, "..", "..", "..");
 }
 
-async function runWebInterface(): Promise<void> {
+async function runWebInterface(
+  flagEnvVars: Record<string, string>,
+  parsedFlagOverrides: Record<string, boolean | string>,
+): Promise<void> {
+  // Propagate flag env vars so child processes (e.g. hatch from the web UI) inherit them.
+  Object.assign(process.env, flagEnvVars);
+
   // Prefer Vite dev server in source checkouts for full local-mode support
   // (HMR, __local endpoints, gateway proxy).
   const webSourceDir = findWebSourceDir();
   if (webSourceDir) {
-    return runViteDevServer(webSourceDir);
+    return runViteDevServer(webSourceDir, flagEnvVars);
   }
 
   const distDir = findWebDistDir();
@@ -638,10 +673,16 @@ async function runWebInterface(): Promise<void> {
   const rawIndexHtml = await Bun.file(path.join(distDir, "index.html")).text();
   const platformUrl = getPlatformUrl();
   const webUrl = getWebUrl();
-  const configJson = JSON.stringify({ webUrl, platformUrl });
+  const safeJson = (v: unknown) =>
+    JSON.stringify(v).replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+  const configJson = safeJson({ webUrl, platformUrl });
+  const hasOverrides = Object.keys(parsedFlagOverrides).length > 0;
+  const flagOverridesSnippet = hasOverrides
+    ? `;window.__VELLUM_FLAG_OVERRIDES__=${safeJson(parsedFlagOverrides)}`
+    : "";
   const indexHtml = rawIndexHtml.replace(
     "</head>",
-    `<script>window.__VELLUM_CONFIG__=${configJson}</script></head>`,
+    `<script>window.__VELLUM_CONFIG__=${configJson}${flagOverridesSnippet}</script></head>`,
   );
 
   const server = Bun.serve({
@@ -766,14 +807,25 @@ async function runWebInterface(): Promise<void> {
   await new Promise(() => {});
 }
 
-async function runViteDevServer(webSourceDir: string): Promise<void> {
+async function runViteDevServer(
+  webSourceDir: string,
+  flagEnvVars: Record<string, string>,
+): Promise<void> {
   const platformUrl = getPlatformUrl();
 
+  // Build VITE_VELLUM_FLAG_* vars so Vite exposes them to the browser bundle.
+  const viteFlagVars: Record<string, string> = {};
+  for (const [envName, value] of Object.entries(flagEnvVars)) {
+    viteFlagVars[`VITE_${envName}`] = value;
+  }
+
   const child = spawn("bun", ["run", "dev"], {
     cwd: webSourceDir,
     stdio: "inherit",
     env: {
       ...process.env,
+      ...flagEnvVars,
+      ...viteFlagVars,
       VITE_PLATFORM_MODE: "false",
       API_PROXY_TARGET: platformUrl,
       VELLUM_WEB_URL: getWebUrl(),
@@ -854,10 +906,12 @@ export async function client(): Promise<void> {
     platformToken,
     bearerToken,
     interfaceId,
+    flagEnvVars,
+    parsedFlagOverrides,
   } = parseArgs();
 
   if (interfaceId === WEB_INTERFACE_ID) {
-    await runWebInterface();
+    await runWebInterface(flagEnvVars, parsedFlagOverrides);
     return;
   }
 

package/src/commands/hatch.ts

@@ -16,6 +16,7 @@ import {
 import type { RemoteHost, Species } from "../lib/constants";
 import { buildNestedConfig } from "../lib/config-utils";
 import { hatchDocker } from "../lib/docker";
+import { parseFeatureFlagArgs, readAmbientFlagEnvVars } from "../lib/flag-args";
 import type { PollResult, WatchHatchingResult } from "../lib/gcp";
 import { hatchLocal } from "../lib/hatch-local";
 import {
@@ -178,11 +179,15 @@ interface HatchArgs {
   watch: boolean;
   sourcePath: string | null;
   configValues: Record<string, string>;
+  flagEnvVars: Record<string, string>;
   analyze: boolean;
 }
 
 function parseArgs(): HatchArgs {
-  const args = process.argv.slice(3);
+  const { envVars: cliFlagVars, remaining: args } = parseFeatureFlagArgs(
+    process.argv.slice(3),
+  );
+  const flagEnvVars = { ...readAmbientFlagEnvVars(), ...cliFlagVars };
   let species: Species = DEFAULT_SPECIES;
   let detached = false;
   let keepAlive = false;
@@ -222,6 +227,9 @@ function parseArgs(): HatchArgs {
       console.log(
         "  --config <key=value>      Set a workspace config value (repeatable)",
       );
+      console.log(
+        "  --flag <key=value>        Set a feature flag override as VELLUM_FLAG_<KEY> env var (repeatable)",
+      );
       console.log(
         "  --analyze                 Emit a structured hatch-timing log line on stdout",
       );
@@ -289,7 +297,7 @@ function parseArgs(): HatchArgs {
       species = arg as Species;
     } else {
       console.error(
-        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --watch, --source <path>, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>, --analyze`,
+        `Error: Unknown argument '${arg}'. Valid options: ${VALID_SPECIES.join(", ")}, -d, --watch, --source <path>, --keep-alive, --name <name>, --remote <${VALID_REMOTE_HOSTS.join("|")}>, --config <key=value>, --flag <key=value>, --analyze`,
       );
       process.exit(1);
     }
@@ -304,6 +312,7 @@ function parseArgs(): HatchArgs {
     watch,
     sourcePath,
     configValues,
+    flagEnvVars,
     analyze,
   };
 }
@@ -538,6 +547,7 @@ export async function hatch(): Promise<void> {
     watch,
     sourcePath,
     configValues,
+    flagEnvVars,
     analyze,
   } = parseArgs();
 
@@ -566,12 +576,12 @@ export async function hatch(): Promise<void> {
   }
 
   if (remote === "local") {
-    await hatchLocal(species, name, watch, keepAlive, configValues);
+    await hatchLocal(species, name, watch, keepAlive, configValues, flagEnvVars);
     return;
   }
 
   if (remote === "docker") {
-    await hatchDocker(species, detached, name, watch, configValues, {
+    await hatchDocker(species, detached, name, watch, configValues, flagEnvVars, {
       sourcePath,
       analyze,
     });

package/src/commands/teleport.ts

@@ -891,6 +891,7 @@ export async function resolveOrHatchTarget(
       false,
       false,
       {},
+      {},
       {
         setupProviderCredentials: false,
       },
@@ -915,6 +916,7 @@ export async function resolveOrHatchTarget(
       targetName ?? null,
       false,
       {},
+      {},
       {
         setupProviderCredentials: false,
       },

package/src/lib/docker.ts

@@ -662,6 +662,7 @@ export async function startContainers(
     bootstrapSecret?: string;
     cesServiceToken?: string;
     extraAssistantEnv?: Record<string, string>;
+    extraGatewayEnv?: Record<string, string>;
     gatewayPort: number;
     imageTags: Record<ServiceName, string>;
     instanceName: string;
@@ -1042,6 +1043,7 @@ export async function hatchDocker(
   name: string | null,
   watch: boolean = false,
   configValues: Record<string, string> = {},
+  flagEnvVars: Record<string, string> = {},
   options: HatchDockerOptions = {},
 ): Promise<void> {
   resetLogFile("hatch.log");
@@ -1321,12 +1323,15 @@ export async function hatchDocker(
       : ownSecret;
 
     emitProgress(4, 6, "Starting containers...");
+    const extraGatewayEnv =
+      Object.keys(flagEnvVars).length > 0 ? flagEnvVars : undefined;
     await startContainers(
       {
         signingKey,
         bootstrapSecret,
         cesServiceToken,
         extraAssistantEnv,
+        extraGatewayEnv,
         gatewayPort,
         imageTags,
         instanceName,

package/src/lib/flag-args.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test, spyOn } from "bun:test";
+
+import { parseFeatureFlagArgs } from "./flag-args";
+
+describe("parseFeatureFlagArgs", () => {
+  test("single flag produces env var and empty remaining", () => {
+    const result = parseFeatureFlagArgs(["--flag", "voice-mode=true"]);
+    expect(result).toEqual({
+      envVars: { VELLUM_FLAG_VOICE_MODE: "true" },
+      remaining: [],
+    });
+  });
+
+  test("multiple flags produce multiple env vars", () => {
+    const result = parseFeatureFlagArgs([
+      "--flag",
+      "a=1",
+      "--flag",
+      "b=0",
+    ]);
+    expect(result).toEqual({
+      envVars: { VELLUM_FLAG_A: "1", VELLUM_FLAG_B: "0" },
+      remaining: [],
+    });
+  });
+
+  test("flags mixed with other args preserves remaining", () => {
+    const result = parseFeatureFlagArgs([
+      "--watch",
+      "--flag",
+      "x=y",
+      "--name",
+      "foo",
+    ]);
+    expect(result).toEqual({
+      envVars: { VELLUM_FLAG_X: "y" },
+      remaining: ["--watch", "--name", "foo"],
+    });
+  });
+
+  test("exits with error when --flag has no following argument", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag"])).toThrow("process.exit");
+    expect(errorSpy).toHaveBeenCalledWith(
+      "Error: --flag requires a key=value argument",
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test("exits with error when value has no equals sign", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag", "noequals"])).toThrow(
+      "process.exit",
+    );
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Error: --flag value must be in key=value format, got "noequals"',
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  test("exits with error when key is not kebab-case", () => {
+    const exitSpy = spyOn(process, "exit").mockImplementation(() => {
+      throw new Error("process.exit");
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    expect(() => parseFeatureFlagArgs(["--flag", "UPPER=true"])).toThrow(
+      "process.exit",
+    );
+    expect(errorSpy).toHaveBeenCalledWith(
+      'Error: invalid flag key "UPPER". Keys must be kebab-case (e.g. "voice-mode")',
+    );
+
+    exitSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+});

package/src/lib/flag-args.ts

@@ -0,0 +1,74 @@
+/** Only allow simple kebab-case keys (e.g. "voice-mode", "ces-tools"). */
+const ALLOWED_KEY_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * Extract repeatable `--flag key=value` pairs from a CLI arg list.
+ *
+ * Each `--flag` consumes the next argument as `key=value`. Keys are validated
+ * against a kebab-case pattern, then converted to env var names of the form
+ * `VELLUM_FLAG_<UPPER_SNAKE>`. All `--flag` pairs are stripped from the
+ * returned `remaining` array so downstream parsers never see them.
+ */
+export function parseFeatureFlagArgs(args: string[]): {
+  envVars: Record<string, string>;
+  remaining: string[];
+} {
+  const envVars: Record<string, string> = {};
+  const remaining: string[] = [];
+
+  let i = 0;
+  while (i < args.length) {
+    if (args[i] === "--flag") {
+      if (i + 1 >= args.length) {
+        console.error("Error: --flag requires a key=value argument");
+        process.exit(1);
+      }
+
+      const pair = args[i + 1]!;
+      const eqIdx = pair.indexOf("=");
+      if (eqIdx === -1) {
+        console.error(
+          `Error: --flag value must be in key=value format, got "${pair}"`,
+        );
+        process.exit(1);
+      }
+
+      const key = pair.slice(0, eqIdx);
+      const value = pair.slice(eqIdx + 1);
+
+      if (!ALLOWED_KEY_RE.test(key)) {
+        console.error(
+          `Error: invalid flag key "${key}". Keys must be kebab-case (e.g. "voice-mode")`,
+        );
+        process.exit(1);
+      }
+
+      const envName = `VELLUM_FLAG_${key.toUpperCase().replace(/-/g, "_")}`;
+      envVars[envName] = value;
+      i += 2;
+    } else {
+      remaining.push(args[i]!);
+      i += 1;
+    }
+  }
+
+  return { envVars, remaining };
+}
+
+const ENV_FLAG_PREFIX = "VELLUM_FLAG_";
+
+/**
+ * Scan `process.env` for ambient `VELLUM_FLAG_*` entries.
+ * Returns them as-is (same `Record<string, string>` shape as
+ * `parseFeatureFlagArgs().envVars`) so callers can merge both
+ * sources with `--flag` args winning over ambient env vars.
+ */
+export function readAmbientFlagEnvVars(): Record<string, string> {
+  const vars: Record<string, string> = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith(ENV_FLAG_PREFIX) && value !== undefined) {
+      vars[key] = value;
+    }
+  }
+  return vars;
+}

package/src/lib/guardian-token.ts

@@ -254,10 +254,51 @@ function releaseRefreshLock(lockPath: string): void {
  * process already rotated it while we waited, we return that fresh token
  * instead of replaying our now-stale refresh token.
  */
+/**
+ * The guardian refresh token is long-lived and replayable, so we only transmit
+ * it over a confidential channel: HTTPS, or a loopback host (local dev, or a
+ * same-host reverse proxy / tunnel agent). Refreshing against a non-loopback
+ * plaintext `http://` URL is refused — an on-path attacker could otherwise
+ * capture the refresh token and rotate it into fresh credentials.
+ *
+ * A user-chosen malicious `https://` destination is intentionally out of scope:
+ * HTTPS protects the channel, and the access token already goes wherever the
+ * configured URL points. This guard targets the plaintext-interception vector.
+ */
+function isLoopbackHostname(hostname: string): boolean {
+  const h = hostname.toLowerCase();
+  return (
+    h === "localhost" ||
+    h === "::1" ||
+    h === "[::1]" ||
+    h === "0:0:0:0:0:0:0:1" ||
+    /^127(?:\.\d{1,3}){3}$/.test(h)
+  );
+}
+
+function isConfidentialRefreshUrl(gatewayUrl: string): boolean {
+  try {
+    const url = new URL(gatewayUrl);
+    return url.protocol === "https:" || isLoopbackHostname(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
 export async function refreshGuardianToken(
   gatewayUrl: string,
   assistantId: string,
 ): Promise<GuardianTokenData | null> {
+  // Never send the long-lived refresh token over a non-loopback plaintext URL.
+  if (!isConfidentialRefreshUrl(gatewayUrl)) {
+    console.warn(
+      `Refusing to refresh the guardian token over an insecure URL (${gatewayUrl}). ` +
+        "The refresh token is only sent over https or a loopback address — " +
+        "use an https URL (e.g. a tunnel) or connect over loopback.",
+    );
+    return null;
+  }
+
   const before = loadGuardianToken(assistantId);
   if (!before) return null;
 

package/src/lib/hatch-local.ts

@@ -164,6 +164,7 @@ export async function hatchLocal(
   watch: boolean = false,
   keepAlive: boolean = false,
   configValues: Record<string, string> = {},
+  flagEnvVars: Record<string, string> = {},
   options: HatchLocalOptions = {},
 ): Promise<HatchLocalResult> {
   const reporter = options.reporter ?? consoleLifecycleReporter;
@@ -234,6 +235,7 @@ export async function hatchLocal(
     runtimeUrl = await startGateway(watch, resources, {
       signingKey,
       bootstrapSecret,
+      envOverrides: flagEnvVars,
     });
   } catch (error) {
     // Gateway failed — stop the daemon we just started so we don't leave

package/src/lib/local.ts

@@ -1057,7 +1057,11 @@ export async function startLocalDaemon(
 export async function startGateway(
   watch: boolean = false,
   resources?: LocalInstanceResources,
-  options?: { signingKey?: string; bootstrapSecret?: string },
+  options?: {
+    signingKey?: string;
+    bootstrapSecret?: string;
+    envOverrides?: Record<string, string>;
+  },
 ): Promise<string> {
   const effectiveGatewayPort = resources?.gatewayPort ?? GATEWAY_PORT;
 
@@ -1083,6 +1087,7 @@ export async function startGateway(
 
   const gatewayEnv: Record<string, string> = {
     ...(process.env as Record<string, string>),
+    ...options?.envOverrides,
     RUNTIME_HTTP_PORT: String(effectiveDaemonPort),
     GATEWAY_PORT: String(effectiveGatewayPort),
     // Pass gateway operational settings via env vars so the CLI does not

package/src/lib/statefulset.ts

@@ -257,6 +257,7 @@ export interface BuildServiceRunArgsOpts extends DockerRunSecrets {
   instanceName: string;
   res: DockerResourceNames;
   extraAssistantEnv?: Record<string, string>;
+  extraGatewayEnv?: Record<string, string>;
   /** Avatar device path, if available. Injected by `docker.ts` after resolving. */
   avatarDevicePath?: string;
 }
@@ -285,6 +286,7 @@ export function buildServiceRunArgs(
     instanceName,
     res,
     extraAssistantEnv,
+    extraGatewayEnv,
     avatarDevicePath,
   } = opts;
 
@@ -346,6 +348,13 @@ export function buildServiceRunArgs(
         }
       }
 
+      // Gateway-only additions (e.g. feature flag env overrides)
+      if (svc === "gateway" && extraGatewayEnv) {
+        for (const [k, v] of Object.entries(extraGatewayEnv)) {
+          args.push("-e", `${k}=${v}`);
+        }
+      }
+
       // Assistant-only computed / optional additions
       if (svc === "assistant") {
         args.push(