feat: add opt-in LAN dashboard access

Author: maxigimenez

README.md

@@ -66,12 +66,22 @@ parallax status      # check health + running projects
 parallax stop
 ```
 
+To access a headless machine's dashboard from a trusted internal network, opt in when starting:
+
+```bash
+parallax start --network-access
+```
+
+Parallax prints the network URL, such as `http://cerebro.local:9372`. Network access is
+unauthenticated and allows dashboard users to approve work and modify configuration, so enable it
+only on a trusted network. Localhost-only access remains the default.
+
 ## CLI
 
 ```bash
 parallax --version
 parallax init                                               # first-time setup wizard
-parallax start [--server-api-port <port>] [--server-ui-port <port>] [--concurrency <count>]
+parallax start [--server-api-port <port>] [--server-ui-port <port>] [--concurrency <count>] [--network-access]
 parallax stop
 parallax status
 parallax open
@@ -92,7 +102,8 @@ See [docs/slack-bot.md](docs/slack-bot.md) for the full setup guide.
 
 ## Dashboard
 
-The dashboard is accessible at `http://localhost:9372` (default):
+The dashboard is accessible at `http://localhost:9372` by default. With
+`parallax start --network-access`, it is also available through the host's network name or IP:
 
 - **Tasks** — live task list with plan approval and log streaming
 - **Projects** — add, edit, and delete project configurations

docs/cli-reference.md

@@ -79,7 +79,7 @@ Notes:
 Start orchestrator and dashboard in background.
 
 ```bash
-parallax start [--server-api-port <port>] [--server-ui-port <port>] [--concurrency <count>]
+parallax start [--server-api-port <port>] [--server-ui-port <port>] [--concurrency <count>] [--network-access]
 ```
 
 `parallax start` reads project and secret configuration from `~/.parallax/config.json`.
@@ -90,8 +90,13 @@ Examples:
 ```bash
 parallax start
 parallax start --server-api-port 9371 --server-ui-port 9372 --concurrency 2
+parallax start --network-access
 ```
 
+`--network-access` binds the dashboard and API to all network interfaces and prints a LAN URL such
+as `http://cerebro.local:9372`. The default remains localhost-only. Network mode is unauthenticated
+and should only be used on a trusted internal network.
+
 ## parallax stop
 
 Stop background processes recorded in the running manifest.
@@ -165,4 +170,5 @@ Common files:
 
 - `config.json`: project and integration configuration (managed by `parallax init` and the dashboard)
 - `running.json`: process manifest (`orchestratorPid`, `uiPid`, ports, start timestamp)
+- `running.json` also records whether the current runtime enabled network access
 - `parallax.db`: SQLite state database

docs/getting-started.md

@@ -83,6 +83,24 @@ What this does:
 - launches the background orchestrator and dashboard
 - reads projects and secrets from `~/.parallax/config.json`
 
+### Optional: access a headless machine over the local network
+
+On a trusted internal network, start Parallax with:
+
+```bash
+parallax start --network-access
+```
+
+The startup output includes a network dashboard URL, for example:
+
+```text
+http://cerebro.local:9372
+```
+
+You can also use the machine's LAN IP address. This mode has no authentication: anyone who can
+reach it can approve tasks and modify Parallax configuration and secrets. Without
+`--network-access`, both the dashboard and API remain bound to localhost.
+
 ## 6. Open the dashboard
 
 ```bash
@@ -91,6 +109,8 @@ parallax open
 
 Or open `http://localhost:9372` in your browser.
 
+For a remote browser, use the network URL printed by `parallax start --network-access`.
+
 The dashboard has three sections (left navigation):
 
 - **Tasks** — live task list, plan approval, log streaming

docs/troubleshooting.md

@@ -51,6 +51,50 @@ parallax stop
 parallax start --server-api-port 3000 --server-ui-port 8080 --concurrency 2
 ```
 
+## Dashboard cannot be reached over the local network
+
+Parallax binds to localhost unless network access is explicitly enabled:
+
+```bash
+parallax stop
+parallax start --network-access
+```
+
+Use the network URL printed at startup or by `parallax status`, for example
+`http://cerebro.local:9372`.
+
+### Vite says the host is not allowed
+
+An error such as:
+
+```text
+Blocked request. This host ("cerebro.local") is not allowed.
+```
+
+means the development dashboard was started without network mode. Restart the full Parallax runtime
+with `parallax start --network-access`; do not edit the installed `vite.config.js`.
+
+### The `.local` hostname does not resolve
+
+On macOS, check the Bonjour hostname:
+
+```bash
+scutil --get LocalHostName
+```
+
+Try `<LocalHostName>.local`, or use the Mac's LAN IP address instead. Ensure both devices are on the
+same network and that client isolation is disabled on the router or access point.
+
+### The hostname resolves but the connection is refused
+
+- Confirm `parallax status` shows a network dashboard URL.
+- Allow incoming connections for Node.js in **System Settings → Network → Firewall**.
+- Confirm ports `9371` and `9372`, or your custom API/UI ports, are not blocked by host or network
+  firewall rules.
+
+Network access has no authentication. Enable it only on a trusted internal network because remote
+dashboard users can approve tasks and modify configuration and secrets.
+
 ## Task actions fail
 
 ### Unknown task id

packages/cli/README.md

@@ -36,6 +36,10 @@ What this flow does:
 
 The dashboard is at `http://localhost:9372` after `parallax start`.
 
+For a trusted internal network, `parallax start --network-access` also exposes the dashboard through
+the machine hostname or LAN IP. This mode is unauthenticated; localhost-only access remains the
+default.
+
 ## How it works
 
 - Parallax stores all configuration and runtime state under `~/.parallax`

packages/cli/src/args.ts

@@ -68,14 +68,25 @@ function parseStrictPort(args: string[], key: string, fallback: number): number
 }
 
 export function parseStartOptions(args: string[]): StartCommandOptions {
-  const allowedFlags = new Set(['--server-api-port', '--server-ui-port', '--concurrency'])
+  const allowedFlags = new Set([
+    '--server-api-port',
+    '--server-ui-port',
+    '--concurrency',
+    '--network-access',
+  ])
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index]
     if (arg.startsWith('--')) {
       const flag = arg.includes('=') ? arg.split('=')[0] : arg
       if (!allowedFlags.has(flag)) {
         throw new Error(`Unsupported flag for parallax start: ${arg}`)
       }
+      if (flag === '--network-access') {
+        if (arg.includes('=')) {
+          throw new Error('--network-access does not accept a value.')
+        }
+        continue
+      }
       if (!arg.includes('=')) {
         index += 1
       }
@@ -98,7 +109,7 @@ export function parseStartOptions(args: string[]): StartCommandOptions {
     throw new Error('--server-api-port and --server-ui-port must be different.')
   }
 
-  return { apiPort, uiPort, concurrency }
+  return { apiPort, uiPort, concurrency, networkAccess: hasFlag(args, 'network-access') }
 }
 
 export function parseStopOptions(args: string[]): StopCommandOptions {

packages/cli/src/commands/start.ts

@@ -3,6 +3,7 @@ import fsSync from 'node:fs'
 import path from 'node:path'
 import { createRequire } from 'node:module'
 import { parseStartOptions } from '../args.js'
+import { buildDashboardUrl, resolveNetworkHostname } from '../network.js'
 import {
   isProcessAlive,
   readFileTail,
@@ -70,6 +71,7 @@ export async function runStart(args: string[], context: CliContext) {
     apiPort: options.apiPort,
     uiPort: options.uiPort,
     concurrency: options.concurrency,
+    networkAccess: options.networkAccess,
   })
   const workspaceDevMode = process.env.NODE_ENV === 'dev'
   const orchestratorStdoutPath = path.join(dataDir, 'orchestrator.stdout.log')
@@ -122,14 +124,20 @@ export async function runStart(args: string[], context: CliContext) {
           '@parallax/ui',
           'start',
           '--host',
-          '0.0.0.0',
+          options.networkAccess ? '0.0.0.0' : '127.0.0.1',
           '--port',
           String(options.uiPort),
         ],
         context.rootDir,
-        {
-          VITE_PARALLAX_API_BASE: `http://localhost:${options.apiPort}`,
-        },
+        options.networkAccess
+          ? {
+              VITE_PARALLAX_API_PORT: String(options.apiPort),
+              PARALLAX_NETWORK_ACCESS: 'true',
+            }
+          : {
+              VITE_PARALLAX_API_BASE: `http://localhost:${options.apiPort}`,
+              PARALLAX_NETWORK_ACCESS: 'false',
+            },
         {
           stdoutPath: uiStdoutPath,
           stderrPath: uiStderrPath,
@@ -168,6 +176,7 @@ export async function runStart(args: string[], context: CliContext) {
           uiPid: uiPid || undefined,
           apiPort: options.apiPort,
           uiPort: options.uiPort,
+          networkAccess: options.networkAccess,
         },
         null,
         2
@@ -179,6 +188,14 @@ export async function runStart(args: string[], context: CliContext) {
     console.log(`${GREEN}✓ Parallax started in background.${RESET}`)
     console.log(`${DIM}Orchestrator PID:${RESET} ${orchestratorPid}`)
     console.log(`${DIM}Dashboard:${RESET} http://localhost:${options.uiPort}`)
+    if (options.networkAccess) {
+      console.log(
+        `${DIM}Network dashboard:${RESET} ${buildDashboardUrl(resolveNetworkHostname(), options.uiPort)}`
+      )
+      console.log(
+        `${YELLOW}Warning: network access is unauthenticated. Anyone on this trusted network can control Parallax and modify its configuration.${RESET}`
+      )
+    }
     console.log(`${DIM}Projects:${RESET} ${storedConfig.projects.length}`)
     console.log('')
     console.log('')

packages/cli/src/commands/status.ts

@@ -1,6 +1,7 @@
 import path from 'node:path'
 import { sleep } from '@parallax/common'
 import { parseStatusOptions } from '../args.js'
+import { buildDashboardUrl, resolveNetworkHostname } from '../network.js'
 import { startSpinner, isProcessAlive } from '../process.js'
 import type { CliContext } from '../types.js'
 
@@ -68,6 +69,11 @@ export async function runStatus(args: string[], context: CliContext) {
       output.push(`${RED}✗ Parallax status: issues detected.${RESET}`)
       output.push(`${DIM}Orchestrator PID:${RESET} ${state.orchestratorPid}`)
       output.push(`${DIM}Dashboard:${RESET} http://localhost:${state.uiPort}`)
+      if (state.networkAccess) {
+        output.push(
+          `${DIM}Network dashboard:${RESET} ${buildDashboardUrl(resolveNetworkHostname(), state.uiPort)}`
+        )
+      }
       output.push('')
       output.push(...errors)
       return
@@ -88,6 +94,11 @@ export async function runStatus(args: string[], context: CliContext) {
     output.push(`${GREEN}✓ Parallax status: healthy.${RESET}`)
     output.push(`${DIM}Orchestrator PID:${RESET} ${state.orchestratorPid}`)
     output.push(`${DIM}Dashboard:${RESET} http://localhost:${state.uiPort}`)
+    if (state.networkAccess) {
+      output.push(
+        `${DIM}Network dashboard:${RESET} ${buildDashboardUrl(resolveNetworkHostname(), state.uiPort)}`
+      )
+    }
 
     if (projects.length > 0) {
       output.push('')

packages/cli/src/config.ts

@@ -58,14 +58,19 @@ export function parseRunningState(raw: string, source: string): RunningState {
     (parsed as { orchestratorPid: number }).orchestratorPid <= 0 ||
     (parsed as { apiPort: number }).apiPort <= 0 ||
     (parsed as { uiPort: number }).uiPort <= 0 ||
+    ('networkAccess' in parsed &&
+      typeof (parsed as { networkAccess?: unknown }).networkAccess !== 'boolean') ||
     ('uiPid' in parsed && typeof (parsed as { uiPid?: unknown }).uiPid !== 'number') ||
     (typeof (parsed as { uiPid?: unknown }).uiPid === 'number' &&
       (parsed as { uiPid: number }).uiPid <= 0)
   ) {
     throw new Error(`Invalid running manifest at ${source}.`)
   }
 
-  return parsed as RunningState
+  return {
+    ...(parsed as RunningState),
+    networkAccess: (parsed as { networkAccess?: boolean }).networkAccess === true,
+  }
 }
 
 export async function loadRunningState(

packages/cli/src/index.ts

@@ -84,7 +84,7 @@ async function resolveDefaultApiBase(): Promise<string> {
 
 function buildEnvConfig(
   dataDir: string,
-  runtime: { apiPort: number; uiPort: number; concurrency: number }
+  runtime: { apiPort: number; uiPort: number; concurrency: number; networkAccess: boolean }
 ) {
   const existingNodeOptions = process.env.NODE_OPTIONS?.trim()
   const sqliteWarningSuppression = '--disable-warning=ExperimentalWarning'
@@ -99,6 +99,7 @@ function buildEnvConfig(
     PARALLAX_SERVER_API_PORT: String(runtime.apiPort),
     PARALLAX_SERVER_UI_PORT: String(runtime.uiPort),
     PARALLAX_CONCURRENCY: String(runtime.concurrency),
+    PARALLAX_NETWORK_ACCESS: String(runtime.networkAccess),
   }
 }