feat(server): add host option for web server

.changeset/server-host-option.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": minor
+---
+
+Add a `--host` option to `kimi web` and `kimi server run` for binding the web UI to non-loopback interfaces.

apps/kimi-code/src/cli/sub/server/daemon.ts

@@ -25,6 +25,7 @@ import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { DEFAULT_LOCK_DIR, getLiveLock, type LockContents } from '@moonshot-ai/server';
 
 import {
+  connectableServerHost,
   DEFAULT_SERVER_HOST,
   DEFAULT_SERVER_PORT,
   isServerHealthy,
@@ -44,6 +45,8 @@ const POLL_INTERVAL_MS = 200;
 const DEFAULT_DAEMON_LOG_LEVEL = 'info';
 
 export interface EnsureDaemonOptions {
+  /** Host/interface the daemon should bind. */
+  host?: string;
   /** Preferred port; on conflict a free port is chosen automatically. */
   port?: number;
   /** Pino log level for the spawned daemon (defaults to `info`). */
@@ -56,6 +59,7 @@ export interface EnsureDaemonOptions {
 
 export interface EnsureDaemonResult {
   readonly origin: string;
+  readonly host: string;
 }
 
 /** Path of the daemon log file (shared with the OS-service log location). */
@@ -65,7 +69,7 @@ export function daemonLogPath(): string {
 
 export function lockConnectHost(lock: LockContents): string {
   const host = lock.host ?? DEFAULT_SERVER_HOST;
-  return host === '0.0.0.0' ? DEFAULT_SERVER_HOST : host;
+  return connectableServerHost(host);
 }
 
 /** True when `host:port` is currently free to bind (nothing listening). */
@@ -178,6 +182,7 @@ export function resolveDaemonProgram(
 }
 
 interface SpawnDaemonChildOptions {
+  host: string;
   port: number;
   logLevel: string;
   debugEndpoints?: boolean;
@@ -193,6 +198,8 @@ export function spawnDaemonChild(options: SpawnDaemonChildOptions): void {
     'server',
     'run',
     '--daemon',
+    '--host',
+    options.host,
     '--port',
     String(options.port),
     '--log-level',
@@ -244,24 +251,27 @@ function sleep(ms: number): Promise<void> {
  * detached process after this returns.
  */
 export async function ensureDaemon(options: EnsureDaemonOptions = {}): Promise<EnsureDaemonResult> {
+  const host = options.host ?? DEFAULT_SERVER_HOST;
   const preferred = options.port ?? DEFAULT_SERVER_PORT;
   const logLevel = options.logLevel ?? DEFAULT_DAEMON_LOG_LEVEL;
 
   // 1. Reuse an already-live daemon if one holds the lock.
   const existing = getLiveLock();
   if (existing) {
+    const existingHost = existing.host ?? DEFAULT_SERVER_HOST;
     const origin = serverOrigin(lockConnectHost(existing), existing.port);
     if (await waitForServerHealthy(origin, REUSE_HEALTH_TIMEOUT_MS)) {
-      return { origin };
+      return { origin, host: existingHost };
     }
     // Live pid but not responding (wedged or mid-boot failure). Fall through
     // and spawn: if it is truly wedged our child loses the lock race and we
     // reconnect below; if it died, stale takeover lets our child claim it.
   }
 
   // 2. No reusable daemon — pick a free port and spawn one detached.
-  const port = await resolveDaemonPort(DEFAULT_SERVER_HOST, preferred);
+  const port = await resolveDaemonPort(host, preferred);
   spawnDaemonChild({
+    host,
     port,
     logLevel,
     debugEndpoints: options.debugEndpoints,
@@ -273,9 +283,10 @@ export async function ensureDaemon(options: EnsureDaemonOptions = {}): Promise<E
   while (Date.now() < deadline) {
     const live = getLiveLock();
     if (live) {
+      const liveHost = live.host ?? DEFAULT_SERVER_HOST;
       const origin = serverOrigin(lockConnectHost(live), live.port);
       if (await isServerHealthy(origin, 500)) {
-        return { origin };
+        return { origin, host: liveHost };
       }
     }
     await sleep(POLL_INTERVAL_MS);

apps/kimi-code/src/cli/sub/server/lifecycle.ts

@@ -249,5 +249,5 @@ function withStatusDetails(
 }
 
 function formatServiceUrl(host: string, port: number): string {
-  return serverOrigin(host === '0.0.0.0' ? DEFAULT_SERVER_HOST : host, port);
+  return serverOrigin(host, port);
 }

apps/kimi-code/src/cli/sub/server/run.ts

@@ -29,8 +29,10 @@ import { createKimiCodeHostIdentity, getHostPackageRoot, getVersion } from '../.
 import { ensureDaemon } from './daemon';
 import {
   DEFAULT_FOREGROUND_LOG_LEVEL,
+  DEFAULT_SERVER_HOST,
   DEFAULT_SERVER_PORT,
   parseServerOptions,
+  serverOriginFromAddress,
   VALID_LOG_LEVELS,
   type ParsedServerOptions,
   type ServerCliOptions,
@@ -51,7 +53,7 @@ export interface StartForegroundHooks {
 }
 
 export interface RunCommandDeps {
-  startServerBackground(options: ParsedServerOptions): Promise<{ origin: string }>;
+  startServerBackground(options: ParsedServerOptions): Promise<{ origin: string; host?: string }>;
   /** Foreground runner; defaults to the real in-process runner when omitted. */
   startServerForeground?: (
     options: ParsedServerOptions,
@@ -65,6 +67,11 @@ export interface RunCommandDeps {
 /** Build the `run` subcommand, mounted under a parent (`server` or top-level). */
 export function buildRunCommand(cmd: Command, options: { defaultOpen: boolean }): Command {
   return cmd
+    .option(
+      '--host <host>',
+      `Host to bind (default ${DEFAULT_SERVER_HOST})`,
+      DEFAULT_SERVER_HOST,
+    )
     .option(
       '--port <port>',
       `Bind port (default ${DEFAULT_SERVER_PORT})`,
@@ -127,7 +134,7 @@ export async function handleRunCommand(
         const readyMs = Date.now() - startedAt;
         deps.stdout.write(
           parsed.logLevel === DEFAULT_FOREGROUND_LOG_LEVEL
-            ? formatReadyBanner(origin, readyMs)
+            ? formatReadyBanner(origin, readyMs, parsed.host)
             : `Kimi server: ${origin}\n`,
         );
         if (opts.open === true) {
@@ -137,11 +144,12 @@ export async function handleRunCommand(
     });
     return;
   }
-  const { origin } = await deps.startServerBackground(parsed);
+  const background = await deps.startServerBackground(parsed);
+  const { origin } = background;
   const readyMs = Date.now() - startedAt;
   deps.stdout.write(
     parsed.logLevel === DEFAULT_FOREGROUND_LOG_LEVEL
-      ? formatReadyBanner(origin, readyMs)
+      ? formatReadyBanner(origin, readyMs, background.host ?? parsed.host)
       : `Kimi server: ${origin}\n`,
   );
   if (opts.open === true) {
@@ -157,14 +165,15 @@ export async function handleRunCommand(
  */
 export async function startServerBackground(
   options: ParsedServerOptions,
-): Promise<{ origin: string }> {
-  const { origin } = await ensureDaemon({
+): Promise<{ origin: string; host: string }> {
+  const { origin, host } = await ensureDaemon({
+    host: options.host,
     port: options.port,
     logLevel: options.logLevel,
     debugEndpoints: options.debugEndpoints,
     idleGraceMs: options.idleGraceMs,
   });
-  return { origin };
+  return { origin, host };
 }
 
 /**
@@ -267,7 +276,7 @@ async function runServerInProcess(
     : { address: running.address };
   running.logger.info(readyFields, mode.daemon ? 'daemon ready' : 'server ready');
 
-  onReady?.(running.address);
+  onReady?.(serverOriginFromAddress(options.host, running.address, options.port));
 
   return new Promise<never>(() => {
     // Keeps the event loop alive; the process ends via shutdown()/process.exit.
@@ -323,7 +332,7 @@ export function resolveServerWebAssetsDir(
   return nativeWebAssetsDir ?? join(getHostPackageRoot(), WEB_ASSETS_DIR);
 }
 
-function formatReadyBanner(origin: string, readyMs: number): string {
+function formatReadyBanner(origin: string, readyMs: number, host: string): string {
   const primary = (text: string): string => chalk.hex(darkColors.primary)(text);
   const title = (text: string): string => chalk.bold.hex(darkColors.primary)(text);
   const dim = (text: string): string => chalk.hex(darkColors.textDim)(text);
@@ -348,7 +357,8 @@ function formatReadyBanner(origin: string, readyMs: number): string {
   ];
   const infoLines = [
     label('URL:      ') + url,
-    label('Network:  ') + muted('local only'),
+    label('Network:  ') + muted(networkLabel(host)),
+    ...(isLocalHost(host) ? [] : [label('Access:   ') + muted('trusted network only')]),
     label('Logs:     ') + muted('off') + dim('  use --log-level info to enable'),
     label('Stop:     ') + muted('kimi server kill'),
     label('Ready:    ') + muted(`${String(Math.max(0, readyMs))} ms`),
@@ -378,6 +388,16 @@ function displayOrigin(origin: string): string {
   return origin.endsWith('/') ? origin : `${origin}/`;
 }
 
+function networkLabel(host: string): string {
+  if (isLocalHost(host)) return 'local only';
+  return `listening on ${host}`;
+}
+
+function isLocalHost(host: string): boolean {
+  const bareHost = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+  return bareHost === DEFAULT_SERVER_HOST || bareHost === 'localhost' || bareHost === '::1';
+}
+
 const DEFAULT_RUN_COMMAND_DEPS: RunCommandDeps = {
   startServerBackground,
   startServerForeground,

apps/kimi-code/src/cli/sub/server/shared.ts

@@ -92,8 +92,38 @@ export function parseLogLevel(raw: string | undefined): ServerLogLevel {
   );
 }
 
+export function connectableServerHost(host: string): string {
+  const bareHost = unbracketHost(host);
+  if (bareHost === '0.0.0.0') return DEFAULT_SERVER_HOST;
+  if (bareHost === '::') return '::1';
+  return bareHost;
+}
+
 export function serverOrigin(host: string, port: number): string {
-  return `http://${host}:${port}`;
+  return `http://${urlHost(connectableServerHost(host))}:${port}`;
+}
+
+export function serverOriginFromAddress(host: string, address: string, fallbackPort: number): string {
+  try {
+    const port = Number.parseInt(new URL(address).port, 10);
+    if (Number.isFinite(port)) {
+      return serverOrigin(host, port);
+    }
+  } catch {
+    // Fall back below if the listening address is unexpectedly malformed.
+  }
+  return serverOrigin(host, fallbackPort);
+}
+
+function urlHost(host: string): string {
+  return host.includes(':') ? `[${host}]` : host;
+}
+
+function unbracketHost(host: string): string {
+  if (host.startsWith('[') && host.endsWith(']')) {
+    return host.slice(1, -1);
+  }
+  return host;
 }
 
 /** Strip `/api/v1` and trailing slashes so user-supplied origins are uniform. */