EmiSwitch

EmiSwitch is an Electron-ready local control board for ports and app/runtime pairing: check port health, clear busy ports, install apps from ZIPs, then pair any app to any free port.

The in-app surface may still say Switchboard / Port Control Board in places; those labels describe the operating board itself. The public project name is EmiSwitch.

Built for serious operations, with just enough personality to keep the logs from feeling lonely.

Main Features

• Port health up front — probe every managed port, mark bad/busy ports, and keep the board honest before pairing.
• Clear ports fast — unassign/clear managed ports, kill stuck listeners, then verify the ports are free and bindable.
• Install from ZIP — import app bundles directly from Replit exports or other ZIP sources, extract them, optionally install dependencies, and verify the result.
• Pair Mode — select a free port, pick an app, and let EmiSwitch bind the app to that port.
• Match any app to any free port — if the requested port is not viable, EmiSwitch can fall back to another healthy managed port.
• Runtime controls — check, kill, and restart local runtime paths from the board.
• Local-first inspectability — visible logs, board state, pairing feedback, and recovery cues instead of hidden magic.

Platform Status

EmiSwitch is a web-first local app with an Electron desktop launch path available.

• macOS supported — primary tested local desktop environment, with Electron available for desktop-window launch.
• Windows & Linux in progress — Electron makes cross-platform packaging a realistic path, but these environments need more testing before being called stable.
• Browser/local-server mode supported — npm run dev remains the simplest development path.

Open Source Release

This repository was prepared for open-source publication as EmiSwitch, from the original local control-board build.

Current Run State

EmiSwitch runs today. The current release can launch locally, show the control board, display available ports, clear managed ports, enter pairing mode, import app ZIPs, and exercise the main runtime/port-management surfaces.

This is still an early open-source preparation build, not a polished stable desktop product. Expect a few rough edges:

• local-first workflow; tested primarily on macOS
• Electron desktop launch is available, but packaged Windows/Linux release hardening is still in progress
• app/window naming is still settling between EmiSwitch, Switchboard, and Port Control Board labels
• port/routing state may need manual refresh, restart, clear-port, or re-pairing during edge cases
• ZIP import/runtime controls are functional surfaces, including Replit-style ZIP imports, but should be treated carefully until hardened by more external testing
• screenshots show the real current interface rather than a cleaned-up marketing mock

In short: working, useful, and inspectable — but not yet guaranteed perfect in every environment.

Preview

More screenshots

Pairing mode

Port selection and actions

Stack

• Electron desktop launch path
• React 19
• Vite
• TypeScript
• Express
• Drizzle ORM
• Tailwind-based UI stack

Feature Details

• Health checking for ports
  • Per-port health probe and quarantine flow (/api/ports/health-one, UI health pulse)
• Clear / unassign ports
  • Managed-port cleanup and free/bindable verification (/api/ports/unassign-all)
• Smart port assignment
  • Bind-by-request with fallback to healthy ports when needed (/api/ports/bind)
• Binding + unbinding workflow
  • Pair Mode, one-app-per-port invariant, and fast reassignment controls in ControlBoard
• ZIP installer/importer
  • Upload + extract + optional dependency install + post-import verification (/api/apps/import-zip, /api/apps/verify-import)
• Runtime controls
  • Check, kill, and restart runtime paths (/api/check-runtime, /api/kill-runtime, /api/restart-runtime)
• Modal-driven operations UI
  • Focused modal flow for install/import actions with progress state and recovery feedback

In short: it’s a control panel that tries to prevent chaos before chaos starts.

Default App Slots

This release is intentionally seeded with three blank slots and no preloaded project bindings:

• blank1
• blank2
• blank3

So first-run state is clean, neutral, and ready for your own app mapping.

Project Structure

• client/ — frontend application
• server/ — backend runtime/API
• shared/ — shared contracts/types
• scripts/ — helper scripts
• docs/ — architecture and release docs

Quick Start

npm install
npm run dev

Optional client-only dev mode:

npm run dev:client

Electron desktop launch:

npm run electron

If you already built the app and only want to reopen the Electron shell:

npm run electron:open

Build:

npm run build

Type check:

npm run check

Environment

Copy .env.example to .env and adjust values as needed.

Release sanity checks

npm run check
npm run build

If both pass, you are in the “ship it (carefully)” zone.

Open Source Governance

See:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• LICENSE
• NOTICE.md

Project Stewardship

• Maintainer: TokenKiosk.ai
• Project: EmiSwitch
• Status: Open-source preparation release