tiennm99/ccs
1
0 Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-10-14 06:17:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add dashboard host binding option

Browse Source
This commit is contained in:
Tam Nhu Tran committed 2026-03-17 09:57:51 -04:00
1 parent 7006e8aebc
commit 553f8ac1e5
13 files changed
+381 -104
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+10 -1
View File
@@ -50,9 +50,18 @@ bun add -g @kaitranntt/ccs # bun (30x faster)
```bash ```bash
ccs config 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` Dashboard updates hub: `http://localhost:3000/updates`
Want to run the dashboard in Docker or pull the prebuilt image? See `docker/README.md`. Want to run the dashboard in Docker or pull the prebuilt image? See `docker/README.md`.
docs/dashboard-auth-cli.md
+2 -2
View File
@@ -1,12 +1,12 @@
# Dashboard Authentication CLI # Dashboard Authentication CLI
Last Updated: 2026-02-26 Last Updated: 2026-03-17
CLI commands for managing CCS dashboard authentication. CLI commands for managing CCS dashboard authentication.
## Overview ## 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. Authentication is **disabled by default** for backward compatibility. Use the CLI to configure and enable it.
docs/project-roadmap.md
+1
View File
@@ -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. - **#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. - **#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 ### Maintainability Hardening Kickoff
src/commands/config-command-options.ts
+115
View File
@@ -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
+44 -99
View File
@@ -3,7 +3,7 @@
* *
* Launches web-based configuration dashboard. * Launches web-based configuration dashboard.
* Ensures CLIProxy service is running for dashboard features. * 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'; import getPort from 'get-port';
@@ -12,97 +12,10 @@ import { startServer } from '../web-server';
import { setupGracefulShutdown } from '../web-server/shutdown'; import { setupGracefulShutdown } from '../web-server/shutdown';
import { ensureCliproxyService } from '../cliproxy/service-manager'; import { ensureCliproxyService } from '../cliproxy/service-manager';
import { CLIPROXY_DEFAULT_PORT } from '../cliproxy/config-generator'; 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 { initUI, header, ok, info, warn, fail } from '../utils/ui';
import { extractOption, hasAnyFlag } from './arg-extractor'; import { isLoopbackHost, resolveDashboardUrls } from './config-dashboard-host';
import { parseConfigCommandArgs, showConfigCommandHelp } from './config-command-options';
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('');
}
/** /**
* Handle config command * Handle config command
@@ -131,8 +44,18 @@ export async function handleConfigCommand(args: string[]): Promise<void> {
await initUI(); await initUI();
const options = parseArgs(args); const parsed = parseConfigCommandArgs(args);
const verbose = options.dev || false; 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(header('CCS Config Dashboard'));
console.log(''); console.log('');
@@ -167,28 +90,50 @@ export async function handleConfigCommand(args: string[]): Promise<void> {
try { try {
// Start server // 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 // Setup graceful shutdown
setupGracefulShutdown(server, wss, cleanup); setupGracefulShutdown(server, wss, cleanup);
const url = `http://localhost:${port}`; const urls = resolveDashboardUrls(options.host, port);
if (options.dev) { if (options.dev) {
console.log(ok(`Dev Server: ${url}`)); console.log(ok(`Dev Server: ${urls.browserUrl}`));
console.log(''); console.log('');
console.log(info('HMR enabled - UI changes will hot-reload')); console.log(info('HMR enabled - UI changes will hot-reload'));
} else { } 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(''); console.log('');
// Open browser // Open browser
try { try {
await open(url, { wait: false }); await open(urls.browserUrl, { wait: false });
console.log(info('Browser opened automatically')); console.log(info('Browser opened automatically'));
} catch { } catch {
console.log(info(`Open manually: ${url}`)); console.log(info(`Open manually: ${urls.browserUrl}`));
} }
console.log(''); console.log('');
src/commands/config-dashboard-host.ts
+77
View File
@@ -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
+1
View File
@@ -314,6 +314,7 @@ Run ${color('ccs config', 'command')} for web dashboard`.trim();
['ccs config thinking --mode auto', 'Set thinking mode'], ['ccs config thinking --mode auto', 'Set thinking mode'],
['ccs config thinking --clear-provider-override codex', 'Clear provider overrides'], ['ccs config thinking --clear-provider-override codex', 'Clear provider overrides'],
['ccs config --port 3000', 'Use specific port'], ['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 <profile>', 'Write profile setup to ~/.claude/settings.json'],
['ccs persist --list-backups', 'List available settings.json backups'], ['ccs persist --list-backups', 'List available settings.json backups'],
['ccs persist --restore', 'Restore settings.json from latest backup'], ['ccs persist --restore', 'Restore settings.json from latest backup'],
src/web-server/index.ts
+2 -1
View File
@@ -17,6 +17,7 @@ import { shutdownUsageAggregator } from './usage/aggregator';
export interface ServerOptions { export interface ServerOptions {
port: number; port: number;
host?: string;
staticDir?: string; staticDir?: string;
dev?: boolean; dev?: boolean;
} }
@@ -113,7 +114,7 @@ export async function startServer(options: ServerOptions): Promise<ServerInstanc
// Start listening // Start listening
return new Promise<ServerInstance>((resolve) => { 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 // Usage cache loads on-demand when Analytics page is visited
// This keeps server startup instant for users who don't need analytics // This keeps server startup instant for users who don't need analytics
resolve({ server, wss, cleanup }); resolve({ server, wss, cleanup });
tests/unit/commands/config-command-options.test.ts
+32
View File
@@ -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
+41
View File
@@ -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
+13
View File
@@ -58,4 +58,17 @@ describe('help command parity', () => {
true 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
+36
View File
@@ -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
+7 -1
View File
@@ -18,7 +18,13 @@ From project root:
bun run dev 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): From `ui/` only (frontend dev server):