feat: add dashboard host binding option

README.md

@@ -50,9 +50,18 @@ bun add -g @kaitranntt/ccs         # bun (30x faster)
 
 ```bash
 ccs config
-# Opens http://localhost:3000
+# Opens a local browser URL and prints bind/network details
 ```
 
+Expose the dashboard to another device on your network:
+
+```bash
+ccs config --host 0.0.0.0
+# Terminal prints the LAN URL to open from the other device
+```
+
+If you expose the dashboard beyond localhost, protect it first with `ccs config auth setup`.
+
 Dashboard updates hub: `http://localhost:3000/updates`
 
 Want to run the dashboard in Docker or pull the prebuilt image? See `docker/README.md`.

docs/dashboard-auth-cli.md

@@ -1,12 +1,12 @@
 # Dashboard Authentication CLI
 
-Last Updated: 2026-02-26
+Last Updated: 2026-03-17
 
 CLI commands for managing CCS dashboard authentication.
 
 ## Overview
 
-The CCS dashboard (`ccs config`) can be protected with username/password authentication. This is useful when running the dashboard on a network-accessible machine.
+The CCS dashboard (`ccs config`) can be protected with username/password authentication. This is useful when running the dashboard on a network-accessible machine or when starting it with `ccs config --host 0.0.0.0`.
 
 Authentication is **disabled by default** for backward compatibility. Use the CLI to configure and enable it.
 

docs/project-roadmap.md

@@ -43,6 +43,7 @@ All major modularization work is complete. The codebase evolved from monolithic
 
 - **#724**: Codex startup is now free-plan safe. CCS defaults new Codex sessions to a cross-plan model and auto-repairs stale paid-only Codex defaults when the active account is on the free plan.
 - **#737**: Dashboard model pickers in Cursor, Copilot, and CLIProxy now use a searchable combobox with autofocus and explicit no-results states for large model catalogs.
+- **#736**: `ccs config` now supports explicit dashboard bind hosts via `--host`, and surfaces remote-access warnings plus reachable URLs when the effective bind is non-loopback.
 
 ### Maintainability Hardening Kickoff
 

src/commands/config-command-options.ts

@@ -0,0 +1,115 @@
+import { extractOption, hasAnyFlag } from './arg-extractor';
+
+export const DEFAULT_DASHBOARD_HOST = '0.0.0.0';
+
+const CONFIG_COMMAND_FLAGS = ['--help', '-h', '--port', '-p', '--host', '-H', '--dev'] as const;
+
+export interface ConfigCommandOptions {
+  port?: number;
+  host: string;
+  hostProvided: boolean;
+  dev: boolean;
+}
+
+export interface ConfigCommandParseResult {
+  help: boolean;
+  error?: string;
+  options: ConfigCommandOptions;
+}
+
+export function parseConfigCommandArgs(args: string[]): ConfigCommandParseResult {
+  const options: ConfigCommandOptions = {
+    host: DEFAULT_DASHBOARD_HOST,
+    hostProvided: false,
+    dev: false,
+  };
+
+  if (hasAnyFlag(args, ['--help', '-h'])) {
+    return { help: true, options };
+  }
+
+  const portOption = extractOption(args, ['--port', '-p'], {
+    knownFlags: CONFIG_COMMAND_FLAGS,
+  });
+  if (portOption.found) {
+    if (portOption.missingValue || !portOption.value) {
+      return { help: false, error: 'Invalid port number', options };
+    }
+
+    const port = parseInt(portOption.value, 10);
+    if (Number.isNaN(port) || port <= 0 || port >= 65536) {
+      return { help: false, error: 'Invalid port number', options };
+    }
+
+    options.port = port;
+  }
+
+  const hostOption = extractOption(portOption.remainingArgs, ['--host', '-H'], {
+    knownFlags: CONFIG_COMMAND_FLAGS,
+  });
+  if (hostOption.found) {
+    const host = hostOption.value?.trim();
+    if (hostOption.missingValue || !host) {
+      return { help: false, error: 'Invalid host value', options };
+    }
+
+    options.host = host;
+    options.hostProvided = true;
+  }
+
+  options.dev = hasAnyFlag(hostOption.remainingArgs, ['--dev']);
+
+  return { help: false, options };
+}
+
+export function showConfigCommandHelp(): void {
+  console.log('');
+  console.log('Usage: ccs config [command] [options]');
+  console.log('');
+  console.log('Open web-based configuration dashboard');
+  console.log('Includes a dedicated Claude IDE Extension page for VS Code-compatible hosts.');
+  console.log('');
+  console.log('Commands:');
+  console.log('  auth               Manage dashboard authentication');
+  console.log('    auth setup       Configure username and password');
+  console.log('    auth show        Display current auth status');
+  console.log('    auth disable     Disable authentication');
+  console.log('');
+  console.log('  image-analysis     Manage image analysis settings');
+  console.log('    --enable         Enable image analysis via CLIProxy');
+  console.log('    --disable        Disable image analysis');
+  console.log('    --timeout <s>    Set analysis timeout (seconds)');
+  console.log('    --set-model <p> <m>  Set model for provider');
+  console.log('');
+  console.log('  Claude IDE Extension');
+  console.log('    Dashboard page   Generate copy-ready setup for VS Code, Cursor, Windsurf');
+  console.log('    Shared settings  Shows preferred ~/.claude/settings.json setup');
+  console.log('    IDE-local JSON   Shows extension-specific environmentVariables snippets');
+  console.log('');
+  console.log('  thinking           Manage thinking/reasoning settings');
+  console.log('    --mode <mode>    Set mode (auto, off, manual)');
+  console.log('    --override <l>   Set persistent override level');
+  console.log('    --clear-override Remove persistent override');
+  console.log('    --tier <t> <l>   Set tier default level');
+  console.log('    --provider-override <p> <t> <l> Set provider tier override');
+  console.log('    --clear-provider-override <p> [t] Remove provider override');
+  console.log('');
+  console.log('Options:');
+  console.log('  --port, -p PORT    Specify server port (default: auto-detect)');
+  console.log('  --host, -H HOST    Bind dashboard server host (default: 0.0.0.0)');
+  console.log('  --dev              Development mode with Vite HMR');
+  console.log('  --help, -h         Show this help message');
+  console.log('');
+  console.log('Examples:');
+  console.log('  ccs config                       Auto-detect available port');
+  console.log('  ccs config --port 3000           Use specific port');
+  console.log('  ccs config --host 0.0.0.0        Show dashboard on your LAN');
+  console.log('  ccs config --host 127.0.0.1      Restrict dashboard to this machine');
+  console.log('  ccs config --dev                 Development mode with hot reload');
+  console.log('  ccs config auth setup            Configure dashboard login');
+  console.log('  ccs config image-analysis        Show image settings');
+  console.log('  ccs config image-analysis --enable Enable feature');
+  console.log('  ccs config thinking              Show thinking settings');
+  console.log('  ccs config thinking --mode auto  Set auto mode');
+  console.log('');
+}

src/commands/config-command.ts

@@ -3,7 +3,7 @@
  *
  * Launches web-based configuration dashboard.
  * Ensures CLIProxy service is running for dashboard features.
- * Usage: ccs config [--port PORT] [--dev]
+ * Usage: ccs config [--port PORT] [--host HOST] [--dev]
  */
 
 import getPort from 'get-port';
@@ -12,97 +12,10 @@ import { startServer } from '../web-server';
 import { setupGracefulShutdown } from '../web-server/shutdown';
 import { ensureCliproxyService } from '../cliproxy/service-manager';
 import { CLIPROXY_DEFAULT_PORT } from '../cliproxy/config-generator';
+import { getDashboardAuthConfig } from '../config/unified-config-loader';
 import { initUI, header, ok, info, warn, fail } from '../utils/ui';
-import { extractOption, hasAnyFlag } from './arg-extractor';
-
-interface ConfigOptions {
-  port?: number;
-  dev?: boolean;
-}
-
-/**
- * Parse command line arguments
- */
-function parseArgs(args: string[]): ConfigOptions {
-  const result: ConfigOptions = {};
-
-  if (hasAnyFlag(args, ['--help', '-h'])) {
-    showHelp();
-    process.exit(0);
-  }
-
-  const portOption = extractOption(args, ['--port', '-p']);
-  if (portOption.found) {
-    if (portOption.missingValue || !portOption.value) {
-      console.error(fail('Invalid port number'));
-      process.exit(1);
-    }
-
-    const port = parseInt(portOption.value, 10);
-    if (!isNaN(port) && port > 0 && port < 65536) {
-      result.port = port;
-    } else {
-      console.error(fail('Invalid port number'));
-      process.exit(1);
-    }
-  }
-
-  result.dev = hasAnyFlag(args, ['--dev']);
-  return result;
-}
-
-/**
- * Show help message
- */
-function showHelp(): void {
-  console.log('');
-  console.log('Usage: ccs config [command] [options]');
-  console.log('');
-  console.log('Open web-based configuration dashboard');
-  console.log('Includes a dedicated Claude IDE Extension page for VS Code-compatible hosts.');
-  console.log('');
-  console.log('Commands:');
-  console.log('  auth               Manage dashboard authentication');
-  console.log('    auth setup       Configure username and password');
-  console.log('    auth show        Display current auth status');
-  console.log('    auth disable     Disable authentication');
-  console.log('');
-  console.log('  image-analysis     Manage image analysis settings');
-  console.log('    --enable         Enable image analysis via CLIProxy');
-  console.log('    --disable        Disable image analysis');
-  console.log('    --timeout <s>    Set analysis timeout (seconds)');
-  console.log('    --set-model <p> <m>  Set model for provider');
-  console.log('');
-  console.log('  Claude IDE Extension');
-  console.log('    Dashboard page   Generate copy-ready setup for VS Code, Cursor, Windsurf');
-  console.log('    Shared settings  Shows preferred ~/.claude/settings.json setup');
-  console.log('    IDE-local JSON   Shows extension-specific environmentVariables snippets');
-  console.log('');
-  console.log('  thinking           Manage thinking/reasoning settings');
-  console.log('    --mode <mode>    Set mode (auto, off, manual)');
-  console.log('    --override <l>   Set persistent override level');
-  console.log('    --clear-override Remove persistent override');
-  console.log('    --tier <t> <l>   Set tier default level');
-  console.log('    --provider-override <p> <t> <l> Set provider tier override');
-  console.log('    --clear-provider-override <p> [t] Remove provider override');
-  console.log('');
-  console.log('Options:');
-  console.log('  --port, -p PORT    Specify server port (default: auto-detect)');
-  console.log('  --dev              Development mode with Vite HMR');
-  console.log('  --help, -h         Show this help message');
-  console.log('');
-  console.log('Examples:');
-  console.log('  ccs config              Auto-detect available port');
-  console.log('  ccs config --port 3000  Use specific port');
-  console.log('  ccs config --dev        Development mode with hot reload');
-  console.log('  ccs config auth setup   Configure dashboard login');
-  console.log('  ccs config              Open dashboard, then choose Claude IDE Extension');
-  console.log('  ccs config image-analysis          Show image settings');
-  console.log('  ccs config image-analysis --enable Enable feature');
-  console.log('  ccs config thinking                Show thinking settings');
-  console.log('  ccs config thinking --mode auto    Set auto mode');
-  console.log('');
-}
+import { isLoopbackHost, resolveDashboardUrls } from './config-dashboard-host';
+import { parseConfigCommandArgs, showConfigCommandHelp } from './config-command-options';
 
 /**
  * Handle config command
@@ -131,8 +44,18 @@ export async function handleConfigCommand(args: string[]): Promise<void> {
 
   await initUI();
 
-  const options = parseArgs(args);
-  const verbose = options.dev || false;
+  const parsed = parseConfigCommandArgs(args);
+  if (parsed.help) {
+    showConfigCommandHelp();
+    process.exit(0);
+  }
+  if (parsed.error) {
+    console.error(fail(parsed.error));
+    process.exit(1);
+  }
+
+  const options = parsed.options;
+  const verbose = options.dev;
 
   console.log(header('CCS Config Dashboard'));
   console.log('');
@@ -167,28 +90,50 @@ export async function handleConfigCommand(args: string[]): Promise<void> {
 
   try {
     // Start server
-    const { server, wss, cleanup } = await startServer({ port, dev: options.dev });
+    const { server, wss, cleanup } = await startServer({
+      port,
+      host: options.host,
+      dev: options.dev,
+    });
 
     // Setup graceful shutdown
     setupGracefulShutdown(server, wss, cleanup);
 
-    const url = `http://localhost:${port}`;
+    const urls = resolveDashboardUrls(options.host, port);
 
     if (options.dev) {
-      console.log(ok(`Dev Server: ${url}`));
+      console.log(ok(`Dev Server: ${urls.browserUrl}`));
       console.log('');
       console.log(info('HMR enabled - UI changes will hot-reload'));
     } else {
-      console.log(ok(`Dashboard: ${url}`));
+      console.log(ok(`Dashboard: ${urls.browserUrl}`));
+    }
+
+    if (!isLoopbackHost(urls.bindHost)) {
+      console.log(info(`Bind host: ${urls.bindHost}`));
+      if (urls.networkUrl) {
+        console.log(info(`Network URL: ${urls.networkUrl}`));
+      }
+    }
+
+    if (options.hostProvided && !isLoopbackHost(urls.bindHost)) {
+      const authConfig = getDashboardAuthConfig();
+      console.log(warn('Dashboard may be reachable from other devices on your network.'));
+      if (!authConfig.enabled) {
+        console.log(info('Protect it before sharing: ccs config auth setup'));
+      }
+      if (!urls.networkUrl) {
+        console.log(info('Use your machine IP or hostname from the other device.'));
+      }
     }
     console.log('');
 
     // Open browser
     try {
-      await open(url, { wait: false });
+      await open(urls.browserUrl, { wait: false });
       console.log(info('Browser opened automatically'));
     } catch {
-      console.log(info(`Open manually: ${url}`));
+      console.log(info(`Open manually: ${urls.browserUrl}`));
     }
 
     console.log('');

src/commands/config-dashboard-host.ts

@@ -0,0 +1,77 @@
+import * as os from 'os';
+
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+const WILDCARD_HOSTS = new Set(['0.0.0.0', '::', '[::]']);
+
+interface NetworkInterfaceCandidate {
+  address: string;
+  family: string | number;
+  internal: boolean;
+}
+
+type NetworkInterfacesMap = Record<string, NetworkInterfaceCandidate[] | undefined>;
+
+export interface DashboardUrls {
+  bindHost: string;
+  browserUrl: string;
+  networkUrl?: string;
+}
+
+export function isLoopbackHost(host: string): boolean {
+  return LOOPBACK_HOSTS.has(host.trim().toLowerCase());
+}
+
+export function isWildcardHost(host: string): boolean {
+  return WILDCARD_HOSTS.has(host.trim().toLowerCase());
+}
+
+export function resolveDashboardUrls(
+  host: string,
+  port: number,
+  networkInterfaces: NetworkInterfacesMap = os.networkInterfaces()
+): DashboardUrls {
+  const bindHost = host.trim();
+
+  if (isWildcardHost(bindHost)) {
+    return {
+      bindHost,
+      browserUrl: `http://localhost:${port}`,
+      networkUrl: getFirstExternalIpv4Url(port, networkInterfaces),
+    };
+  }
+
+  return {
+    bindHost,
+    browserUrl: `http://${formatHostForUrl(bindHost)}:${port}`,
+  };
+}
+
+function getFirstExternalIpv4Url(
+  port: number,
+  networkInterfaces: NetworkInterfacesMap
+): string | undefined {
+  for (const interfaceName of Object.keys(networkInterfaces)) {
+    const candidates = networkInterfaces[interfaceName];
+    if (!candidates) {
+      continue;
+    }
+
+    for (const candidate of candidates) {
+      const family =
+        typeof candidate.family === 'string' ? candidate.family : String(candidate.family);
+      if (family === 'IPv4' && !candidate.internal) {
+        return `http://${candidate.address}:${port}`;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function formatHostForUrl(host: string): string {
+  if (host.includes(':') && !host.startsWith('[') && !host.endsWith(']')) {
+    return `[${host}]`;
+  }
+
+  return host;
+}

src/commands/help-command.ts

@@ -314,6 +314,7 @@ Run ${color('ccs config', 'command')} for web dashboard`.trim();
     ['ccs config thinking --mode auto', 'Set thinking mode'],
     ['ccs config thinking --clear-provider-override codex', 'Clear provider overrides'],
     ['ccs config --port 3000', 'Use specific port'],
+    ['ccs config --host 0.0.0.0', 'Expose dashboard to other devices on your LAN'],
     ['ccs persist <profile>', 'Write profile setup to ~/.claude/settings.json'],
     ['ccs persist --list-backups', 'List available settings.json backups'],
     ['ccs persist --restore', 'Restore settings.json from latest backup'],

src/web-server/index.ts

@@ -17,6 +17,7 @@ import { shutdownUsageAggregator } from './usage/aggregator';
 
 export interface ServerOptions {
   port: number;
+  host?: string;
   staticDir?: string;
   dev?: boolean;
 }
@@ -113,7 +114,7 @@ export async function startServer(options: ServerOptions): Promise<ServerInstanc
 
   // Start listening
   return new Promise<ServerInstance>((resolve) => {
-    server.listen(options.port, () => {
+    server.listen(options.port, options.host, () => {
       // Usage cache loads on-demand when Analytics page is visited
       // This keeps server startup instant for users who don't need analytics
       resolve({ server, wss, cleanup });

tests/unit/commands/config-command-options.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  DEFAULT_DASHBOARD_HOST,
+  parseConfigCommandArgs,
+} from '../../../src/commands/config-command-options';
+
+describe('config command options parser', () => {
+  it('defaults to wildcard host without explicit override', () => {
+    const result = parseConfigCommandArgs([]);
+
+    expect(result.help).toBe(false);
+    expect(result.error).toBeUndefined();
+    expect(result.options.host).toBe(DEFAULT_DASHBOARD_HOST);
+    expect(result.options.hostProvided).toBe(false);
+  });
+
+  it('parses explicit host and port overrides', () => {
+    const result = parseConfigCommandArgs(['--host', '0.0.0.0', '--port', '4100']);
+
+    expect(result.error).toBeUndefined();
+    expect(result.options.host).toBe('0.0.0.0');
+    expect(result.options.hostProvided).toBe(true);
+    expect(result.options.port).toBe(4100);
+  });
+
+  it('rejects missing host values', () => {
+    const result = parseConfigCommandArgs(['--host']);
+
+    expect(result.error).toBe('Invalid host value');
+  });
+});

tests/unit/commands/config-dashboard-host.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  isLoopbackHost,
+  isWildcardHost,
+  resolveDashboardUrls,
+} from '../../../src/commands/config-dashboard-host';
+
+describe('config dashboard host helpers', () => {
+  it('detects loopback and wildcard hosts', () => {
+    expect(isLoopbackHost('localhost')).toBe(true);
+    expect(isLoopbackHost('127.0.0.1')).toBe(true);
+    expect(isWildcardHost('0.0.0.0')).toBe(true);
+    expect(isWildcardHost('::')).toBe(true);
+  });
+
+  it('returns localhost browser URL and LAN URL for wildcard host', () => {
+    const urls = resolveDashboardUrls('0.0.0.0', 3000, {
+      en0: [
+        {
+          address: '192.168.1.25',
+          netmask: '255.255.255.0',
+          family: 'IPv4',
+          mac: '00:00:00:00:00:00',
+          internal: false,
+          cidr: '192.168.1.25/24',
+        },
+      ],
+    });
+
+    expect(urls.browserUrl).toBe('http://localhost:3000');
+    expect(urls.networkUrl).toBe('http://192.168.1.25:3000');
+  });
+
+  it('returns explicit host URL for loopback bindings', () => {
+    const urls = resolveDashboardUrls('127.0.0.1', 3000, {});
+
+    expect(urls.browserUrl).toBe('http://127.0.0.1:3000');
+    expect(urls.networkUrl).toBeUndefined();
+  });
+});

tests/unit/commands/help-command-parity.test.ts

@@ -58,4 +58,17 @@ describe('help command parity', () => {
       true
     );
   });
+
+  test('root help documents dashboard host binding example', async () => {
+    const lines: string[] = [];
+    console.log = (...args: unknown[]) => {
+      lines.push(args.map((arg) => String(arg)).join(' '));
+    };
+
+    await handleHelpCommand();
+
+    const rendered = stripAnsi(lines.join('\n'));
+    expect(rendered.includes('ccs config --host 0.0.0.0')).toBe(true);
+    expect(rendered.includes('Expose dashboard to other devices on your LAN')).toBe(true);
+  });
 });

tests/unit/web-server/start-server-host.test.ts

@@ -0,0 +1,36 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import type { AddressInfo } from 'net';
+
+import { startServer } from '../../../src/web-server';
+
+const instances: Array<Awaited<ReturnType<typeof startServer>>> = [];
+
+afterEach(async () => {
+  while (instances.length > 0) {
+    const instance = instances.pop();
+    if (!instance) {
+      continue;
+    }
+
+    instance.cleanup();
+    await new Promise<void>((resolve) => instance.server.close(() => resolve()));
+  }
+});
+
+describe('startServer host binding', () => {
+  it('binds to an explicit loopback host', async () => {
+    const instance = await startServer({ port: 0, host: '127.0.0.1' });
+    instances.push(instance);
+
+    const address = instance.server.address() as AddressInfo;
+    expect(address.address).toBe('127.0.0.1');
+  });
+
+  it('binds to wildcard host when requested', async () => {
+    const instance = await startServer({ port: 0, host: '0.0.0.0' });
+    instances.push(instance);
+
+    const address = instance.server.address() as AddressInfo;
+    expect(['0.0.0.0', '::']).toContain(address.address);
+  });
+});

ui/README.md

@@ -18,7 +18,13 @@ From project root:
 bun run dev
 ```
 
-This starts the CCS server and serves the dashboard at `http://localhost:3000`.
+This starts the CCS server, opens a local browser URL, and prints bind/network details for the dashboard.
+
+For LAN access during development, run:
+
+```bash
+bun run dev -- --host 0.0.0.0
+```
 
 From `ui/` only (frontend dev server):