Skip to content
Core-X Docs

Unified UI

The UI lives at core-x/ui/ and is a Vite + React + Three.js application with 14 adaptive modes. Exact versions are in core-x/ui/package.json (currently React ^19, Three.js ^0.183, Vite ^6).

Run (Dev)

Terminal window
cd ~/core-x-kbllr_0/core-x/ui
npm install        # first time
npm run dev        # starts on :5200

Note: The main launcher (launch-core-x.sh) starts the UI automatically. Use the manual command above only for isolated UI development.

Scripts (from package.json)

Terminal window
npm run dev        # Vite dev server (:5200)
npm run build      # tsc && vite build
npm run preview    # Vite preview of production build

How It Works

  • UI talks to gateway (:8090) for all LLM/RAG/vision/audio requests via OpenResponses
  • UI talks to event bus (:8085) via SSE for real-time agent-to-agent events
  • UI talks to observability API (:5201) for service health monitoring
  • The runtime shell has floating glass chrome elements (topbar, nav rail, session HUD) that are all draggable
  • Launcher is now the canonical app activation surface:
    • per-app requirements are defined in core-x/lib/app-profiles.ts (services + model lanes + defaults)
    • app activation calls POST /api/apps/activate (ensure services + release previous + prepare current)
    • launcher terminal controls POST /api/services/start|stop|restart
    • launcher terminal streams structured events from GET /api/logs/stream
  • Launcher app cards are dense operational cards (tier, lanes, model defaults, service readiness, missing deps)
  • core-x-disk study is exposed as a first-class launcher app (offline mode, no MLX service dependency)

Key UI Directories

core-x/ui/src/
├── modes/       # 14 adaptive modes (chat, canvas, voice, image, code, research, ...)
├── components/  # 33 shared component dirs
├── hooks/       # 31 custom hooks (useDraggable, useServiceHealth, ...)
├── lib/         # 42 utility modules (env, app-registry, openresponses, ...)
├── launcher/    # Launcher home (LauncherHome, AppGrid, Terminal, ServiceChips)
├── runtime/     # Runtime shell (RuntimeShell, RuntimeTopBar, RuntimeNavRail, SessionHUD)
└── styles/      # core.css + Tailwind config


core-x/lib/
└── app-profiles.ts  # canonical per-app activation config shared by UI + UI API

Health Dashboard

When the full stack is healthy, every service returns HTTP 200 with a JSON body:

Terminal window
$ curl -s http://localhost:8090/health | python3 -m json.tool
{
    "status": "ok"
}

Quick all-ports sweep:

Terminal window
for port in 8090 8091 8092 8085 8093 8095 8096 8083 8094 8084; do
  code=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:$port/health 2>/dev/null || echo "---")
  printf ":%s  %s\n" "$port" "$code"
done

Expected output (standard tier — no vision/video):

:8090  200   ← gateway
:8091  200   ← mlx-llm
:8092  200   ← mlx-rag
:8085  200   ← event-bus
:8093  200   ← mlx-audio
:8095  200   ← mlx-embed
:8096  200   ← said
:8083  ---   ← mflux (standard tier, not auto-started)
:8094  ---   ← mlx-vision (full tier only)
:8084  ---   ← video (full tier only)

The launcher’s --status flag prints a formatted table with green/red indicators for each service.