Dashboard Migration Research 2026

Vox Dashboard Migration Research (April 2026)

Scope

This document synthesizes the architectural decisions and prerequisites discovered during the migration of the Vox orchestration UI from an editor-bound vox-vscode webview to a standalone crates/vox-dashboard crate served via Axum.

Note: This research has been ratified and superseded by ADR 024.

Decision

We have decoupled the orchestration dashboard from the VS Code extension, opting for a local Axum-served Single Page Application (SPA). The SPA is bundled at compile-time into the vox-orchestrator binary using include_dir!. This eliminates the need for Node.js at runtime, removes the dependency on the VS Code extension host, and allows universal access from any browser or editor via vox dashboard.

Transport

The dashboard communicates with the backend using the existing HTTP Gateway provided by vox-orchestrator:

• WebSocket (/v1/ws): Used for bidirectional event streaming (e.g., voxStatus, gamifyUpdate, a2aTasks). The server pushes agent_event envelopes which are handled by the frontend’s VoxTransport.
• Fetch (/v1/tools/call): Used for executing MCP tools and polling initial state (e.g., vox_orchestrator_status).

This avoids inventing a new ad-hoc protocol and fully utilizes the existing standardized MCP JSON-RPC/HTTP bridge.

Auth

To facilitate a seamless developer experience on localhost, we auto-set allow_unauthenticated = true when the gateway binds to 127.0.0.1 and VOX_DASHBOARD_ENABLED=1 is set. This permits the browser to interact with the orchestration backend without requiring a Bearer token, mimicking the zero-config experience of the legacy VS Code webview. Remote access or connections outside 127.0.0.1 still enforce strict bearer token validation.

Build

The frontend is a Vite 6 SPA (React 19). During the Rust build process, the dist/ directory generated by pnpm run build is embedded into the crate via the embedded-assets feature. This results in a single, portable binary.

Component reuse

All 13 core React components from apps/editor/vox-vscode/webview-ui/src/components/ were ported verbatim. The primary modifications involved:

1. Swapping vscode.postMessage for voxTransport.callTool.
2. Stripping var(--vscode-*) CSS tokens in favor of neutral index.css design system classes (e.g., text-foreground, bg-background, border-border).

Rejected alternatives

• Tauri: Adds excessive build-time dependencies (WebKit/WebView2 libraries) that increase friction for new contributors.
• Electron: Reintroduces the heavy Node.js dependency we are trying to eliminate.
• Bundled VSCode (Browser): Carries significant licensing and payload size overhead.
• Native Rust GUI (egui/Iced): Would require rewriting all 13 complex TSX components from scratch, breaking feature parity and losing the rich React ecosystem (Radix UI, Framer Motion, xyflow).

Vox GUI language roadmap

The transition to an Axum-served dashboard lays the foundation for future “Vox GUI language” capabilities. Deferred to Phase 9 of the GUI-native roadmap (vox-gui-native-roadmap-2026.md §Phase 9). Until that phase lands, dashboards rely on hand-authored TSX components. Once Phase 9 ships, .vox agent code will be able to programmatically define custom dashboard views and forms, rendered dynamically by the React shell over the /v1/ws transport.