Skip to content

Add web server mode for headless/remote access#28

Open
nandanadileep wants to merge 2 commits into
doctly:mainfrom
nandanadileep:feat/web-server-mode
Open

Add web server mode for headless/remote access#28
nandanadileep wants to merge 2 commits into
doctly:mainfrom
nandanadileep:feat/web-server-mode

Conversation

@nandanadileep

Copy link
Copy Markdown

Implements the feature requested in #23 — an optional HTTP + WebSocket server mode that serves the Switchboard UI from any browser, no Electron or desktop environment required.

How it works

A single new entry point (web-server.js) boots an HTTP server that:

  • Serves the existing public/ frontend as static files
  • Exposes all IPC handler logic as a single POST /api/invoke endpoint
  • Opens a WebSocket connection on the same port for terminal I/O and all push events (terminal-data, projects-changed, cli-busy-state, mcp-open-diff, etc.)

A browser-side shim (public/web-api.js) implements the exact same window.api interface as preload.js using fetch + WebSocket. It's loaded as the first script in index.html and no-ops in Electron mode (where window.api is already set by the preload).

No new runtime dependencies — the server uses Node's built-in http module plus the ws package that was already in dependencies.

Usage

# Default — localhost:3000
npm run web

# Custom port / bind to all interfaces for LAN access
npm run web -- --port 8080 --host 0.0.0.0

# Supply your own token instead of the auto-generated one
npm run web -- --token mysecrettoken
# or
SWITCHBOARD_TOKEN=mysecrettoken npm run web

On startup the token is printed to stdout:

  Switchboard web server running
  URL:   http://localhost:3000
  Token: a3f9...

  Open the URL in your browser. When prompted, enter the token above.
  Or append ?token=<token> to the URL to authenticate automatically.

All HTTP and WebSocket requests require a bearer token — either via Authorization: Bearer <token> header or ?token=<token> query parameter.

Changes

File Change
web-server.js New — standalone HTTP + WS server (~450 lines)
public/web-api.js New — browser window.api shim (~130 lines)
public/index.html +1 line — load web-api.js as first script
package.json +1 line — "web": "node web-server.js" script

Electron mode is completely unchanged.

Closes #23

Implements an optional HTTP + WebSocket server that serves Switchboard
from any browser without requiring Electron or a desktop environment.

- web-server.js: standalone Node server (no new deps — uses built-in
  http plus the existing ws package). Mirrors all ipcMain.handle
  channels as POST /api/invoke endpoints. Terminal I/O and push events
  (terminal-data, projects-changed, cli-busy-state, etc.) flow over a
  single authenticated WebSocket connection.

- public/web-api.js: browser-side shim that implements the same
  window.api interface as preload.js using fetch + WebSocket. No-ops
  in Electron mode (window.api already set by preload).

- public/index.html: load web-api.js as the first script so it can
  define window.api before any other module runs.

- package.json: add 'web' npm script for convenience.

Usage:
  npm run web [-- --port 3000 --host 0.0.0.0]

A bearer token is generated (or supplied via --token / SWITCHBOARD_TOKEN)
and printed on startup. Append ?token=<token> to the URL or enter it
when prompted.

Closes doctly#23
@abasiri

abasiri commented Apr 16, 2026

Copy link
Copy Markdown
Contributor

Sorry about the slowness, I should be able to get to this soon.

@saxenasaksham

Copy link
Copy Markdown

This is super, this helped me to use Switchboard for the WSL scenario. All my work is done inside WSL and Windows is just there as the host OS. The web interface runs inside WSL and I can actually do things now on the main browser, so yay! Previously this was impossible as the native electron app built on top of Linux was garbage and slow. The rendering was way off but since it was WSL I didn't want to setup too much GUI stuff inside it. This is cool though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature request: Web UI / headless server mode for remote access

4 participants