quixos/quixos-instance/project-visualizer

Project Visualizer

React SPA for inspecting Quixos packages through the orchestrator control plane.

Run

cd quixos-instance/project-visualizer
nix develop
yarn install
yarn dev

Then open the Vite URL and enter:

• control URL: usually http://127.0.0.1:6246
• control secret: QUIXOS_CONTROL_SECRET

When the visualizer is opened on localhost / 127.0.0.1, it uses the normal local port layout:

• control plane: :6246
• surface relay: :6247

When it is opened on any non-localhost host, it assumes a same-origin reverse-proxy layout:

• control plane: /control
• surface relay: /relay

Standalone popouts and QR/shared links follow the same rule.

Home Screen App

The visualizer ships a web app manifest and Apple home-screen metadata. The manifest starts at /#mode=device, so launching the installed app opens the device-wrapper page rather than the full visualizer. On iPad, open the reverse-proxied visualizer URL in Safari, use Share -> Add to Home Screen, then launch it from the icon. Safari should open it in standalone mode without normal browser chrome.

The control URL and control secret are stored in browser local storage for that origin. If the home-screen app starts with a blank secret, enter it once from the menu. The visualizer also retries status fetches and websocket connections, so restarting the orchestrator should not require removing/re-adding the home-screen app.

Shared QR links no longer point directly at one fixed surface forever. They open a stable device-wrapper page that:

• stores a stable device id in browser local storage
• keeps a live websocket session to the orchestrator
• renders whatever browser surface the orchestrator currently has assigned to that device
• can be reconfigured later from the visualizer Devices tab or qx-control assign ...
• configured assignments take effect on the next cutover
• visualizer-side assignment also updates the committed device-assignment config so later cutovers keep the same mapping

Recommended Caddy layout:

quixos-orchestrator.tutti.internal.tutti.syntaxblitz.net {
  reverse_proxy / 10.20.0.4:4173

  handle_path /control/* {
    reverse_proxy 10.20.0.4:6246
  }

  handle_path /relay/* {
    reverse_proxy 10.20.0.4:6247 {
      header_up X-Forwarded-Prefix /relay
    }
  }
}

The X-Forwarded-Prefix header is required so the relay can emit browser-surface bundle URLs under /relay/surfaces/....

What it does

• fetches /status
• fetches and mutates device state through /devices, /devices/assign, /devices/rename, /devices/identify, /devices/stop-identify, /devices/remove, and the device websocket at /device-ws
• fetches /describe on demand
• opens browser WebSocket sessions to /ws
• explicitly opens root state contexts
• explicitly calls functions, gets values, watches values, and subscribes to events
• special-cases relay-backed quixos.ui.surface/v1 browser-module surfaces by mounting their browser bundles in the page
• exposes a Devices tab for renaming devices, queuing the currently focused browser surface for the next cutover, triggering identify overlays, and removing saved device mappings
• uses the shared surface relay websocket and asset server on port 6247
• still supports legacy relay-backed Remote DOM surfaces while newer browser-surface packages migrate over