Skip to content

Dashboard development

React Dashboard

The standard frontend is developed as a pnpm workspace under dashboard/:

dashboard/
  apps/web                 React browser application and nginx image
  apps/cli                 standalone command line client and terminal UI
  apps/api                 license verification module, issuer and API runtime image
  packages/contracts       typed API contracts and response validation
  packages/api-client      authenticated transport shared by all clients
  packages/core            role, formatting, catalog, and selection logic

It deliberately uses the existing backend API and runtime resources. It does not duplicate Kubernetes access, Keycloak administration, model discovery, or reconciliation logic in a client. The CLI and TUI reuse the same contracts, API client, and core rules without importing React.

Normal dashboard-source pushes to main and develop build and automatically promote a coordinated Web/API/CLI image set after required CI succeeds. The Deployments still use immutable digests, and feature-branch/manual builds remain explicit promotion candidates. Verify promotion and live convergence separately in dashboard image promotion.

The React frontend is the only browser dashboard, deployed as dashboard/ai-appliance-dashboard. Open https://<mDNS-domain>/ (by default https://magicstick.local/) or the configured public-domain root. The existing Service and primary routes remain in place. Each SSO host uses its own callback and host-only __Host-MagicStickAccessToken cookie. The local route keeps lab42.io/mdns.enabled: "true", so kdns publishes the primary hostname when the route is accepted and the Gateway has an address. First-run setup and the physical CLI/TUI console keep their existing handoff URLs and do not require another dashboard address.

Long-lived browser login is Keycloak/Envoy policy, not a second Dashboard authentication mechanism. The native Remember me checkbox selects the session lifetime; no new UI page, public API, local-storage token or service-account realm permission is needed. Identity validation covers migration and accelerated protocol checks.

The former ConfigMap frontend and separate preview Deployment, Service, route, OIDC policy and mDNS hostname are removed. There is no old-UI fallback link. See operations for upgrade cleanup, including old containers retained by another server-side-apply field manager (FailedMount/Flux HealthCheckFailed) and external GitOps installations that disable pruning. The opt-in administrator migration helper preserves the new frontend and runtime data; it does not add workload-write access to the API.

The React implementation retains the established tab-by-tab feature contract:

Area React parity contract
Overview Appliance and object counts, discovered module and instance URLs with local/public/direct classification and copy/open actions, plus appliance, module, instance, model, removal, and Flux attention items.
Models One catalog-driven local configuration form for Ollama, vLLM and experimental Omni Create/Edit; shared CPU controls and engine-specific source/hardware/memory options; CPU and per-GPU memory gauges; presets, direct references and registry discovery; metadata, memory estimates, revision-safe editing, lifecycle and logs.
Services Catalog-driven Applications, AI Runtime, and Platform groups; dependency-aware enable/disable controls; parameters; credentials; collapsible instances; progress, messages, routes, removal, and all OpenClaw, Hermes, Paperclip, KubeOpenCode, Odysseus, and Pi Coding Agent create options.
API Access Endpoint display/copy, named-key creation, one-time secret display/copy, non-secret metadata, refresh, and guarded revocation.
Mesh Administrator-only top-level page immediately after API Access; optional module activation, membership, invitations, local-model sharing, relay configuration, and status. Former Settings Mesh links redirect here.
Kubernetes Access OIDC readiness, role explanations and warnings, user search/pagination, access assignment/removal, and readiness-guarded kubeconfig download/copy.
Federated SSO Entitlement status, stable issuer and per-provider callback, OIDC/SAML metadata validation, redacted provider state, exact role mappings, guarded save/delete, and local-recovery guidance.
System Category tabs for Settings, License, Users, Hardware, System Status and Computer power. Settings retains its own subtabs, including the identity-gated Local console level (/api/console-access, shared with the CLI console-access command and the TUI Settings tab). System Status has a separate role-filtered tab bar: Overview resource counts and summaries; GPU Operators; Flux reasons/messages; Network & routes; administrator-only Model cache at #/system/status/model-cache; and license-free administrator regression execution/reports at #/system/status/regression. Only the selected status tool mounts and queries its API, independent of resource-status loading/errors. Old #/system/model-cache and #/system/regression hashes redirect to the matching nested status page. Existing Settings, License and Users compatibility links and administrator-only power controls remain intact.

dashboard/apps/web/src/FeatureParity.test.tsx protects these user-visible contracts independently of the smaller application-shell tests. Catalog and API behavior remain covered by the existing Python dashboard tests.

Temporary dependency patch

The frozen workspace applies picomatch@4.0.7.patch for GHSA-fc5q-39xc-vjpf. An unescaped glob star inside a repeated extglob can produce nested unbounded regular-expression quantifiers even with a single branch. The patch uses the parser's existing conservative literal fallback for that risky form, after its existing safe character-star reduction. Such a risky pattern is treated as literal text, not executed as a repeated glob. This deliberately changes those patterns; it is not a general proof that arbitrary regular expressions are safe. Quoted, escaped and simple bracket-literal stars retain their normal meaning. Nested extglob operators are not mistaken for plain glob stars; known POSIX classes retain their bracket-literal meaning too. Disabling the upstream recursion protection explicitly remains unsafe for untrusted patterns and is not done by the reviewed build consumers.

pnpm-lock.yaml binds the patch checksum and every transitive consumer. The Web and CLI Docker build contexts include the patch before frozen installation; the regression image copies the complete workspace. The upstream version, tarball integrity and MIT notices are retained rather than assigning a fictitious fixed version. pnpm test runs test:dependency-patches before the existing client suites. The existing SEC-03 supply-chain owning selection also invokes DependencyPatchTests, checking the actual installed matcher, lock graph, build contexts and strict audit defaults.

The unpatched counterexample must exceed a bounded child-process budget; with the patch, the same short attack and its variants finish and preserve the literal fallback. Ordinary file/test globs and both client builds are separate compatibility checks, not appliance acceptance.

Compatibility comparison against the exact upstream 4.0.7 revision 6bb40679c218cefba5d4e9662408c5fdf699a8bb runs its unchanged Mocha tests: the baseline has 1,983 passes; with this mitigation 1,979 pass and four upstream assertions retain their old expectation for the intentionally literalized risky forms (+(*)c, *(a*|b) and */*(W*, *)*). These four assertions are not reported as passed or removed. The project-specific counterexamples additionally exercise bounded rejection of those repeated-wildcard forms with failing suffixes. The ordinary reviewed Web/CLI test/build checks are separate evidence; this candidate is not a fully upstream-compatible general-purpose replacement.

GitHub withdrew the advisory on 18 November 2026; this did not change the npm package contents. The local patch and its coverage remain in place. The Dependency security workflow always runs the unfiltered pnpm audit --audit-level high on the frozen graph. High or critical findings and registry failures still fail the check. Removing the patch is a separate compatibility decision that requires a reviewed lock and inventory update, matcher and client tests, and exact-commit CI.

First-run setup sessions

The separate local setup application is defined in magic-cluster/platform/identity/setup-configmap.yaml. Its console code remains valid throughout Pending, Claimed, Applying, and Failed; Claimed is not an exclusive-browser reservation. Each successful code entry issues an independent, expiring, signed session and CSRF binding. The signing key persists in the existing setup-session Secret; older hashed sessions remain valid until expiry. Retries and a setup-service restart do not evict other browsers.

Validated completion attempts retain only non-secret configuration fields for prefilling; no human password or recovery code is stored. A single setup replica serializes completion and uses Recreate during upgrades. Only after settings and both users are configured does the service mark setup Completed, close code/session authorization, and remove setup credentials. Credential cleanup is retryable; an HTTP disconnect or cleanup error cannot demote Completed. The existing dashboard handoff readiness/grace checks remain in effect.

Backend retry/expiry/concurrency counterexamples are in magic-cluster/platform/identity/tests/test_setup_sessions.py; desktop/mobile browser fixtures run the actual embedded setup assets in dashboard/apps/web/e2e/setup.spec.ts. These isolated checks do not prove a fresh physical installation or live Keycloak/Gateway convergence. See first administrator setup for the user flow.

Updating The Dashboard

The dashboard may read Kubernetes status and create or patch ModuleActivation, ModelActivation, and AppInstance resources. It must not directly create workloads, Flux Kustomizations, HelmReleases, or specialized operator CRs. The administrator regression page also creates RegressionRun runtime intent; the same operator owns its Job. The API provisions only its private generated test identity, exposes sanitized artifacts and reclaims the identity after exact Pod termination and verified setup recovery. Interrupted runs retain their exact generated identity and private restoration receipt for the next run. It never receives a user-supplied test script or image. Optional cleanup status is independent of test outcome and credentialsCleaned. The runner verifies exact root/worker journals and borrowed settings before reporting verified; missing legacy evidence stays unknown. The API preserves the run-owned account for unverified mutating cleanup, even after Job termination. The main All checks metrics use complete result.counts and blockedCounts. Closed Executable scenarios details use executionCounts and executionBlockedCounts; live evidenceCounts and phases stay separate. Never reconstruct global totals from overlapping phases or the limited case list. Missing final counts remain unavailable; only explicitly preliminary scenario progress may be shown. 100% denotes completed execution, not a passing outcome. New HTML/text exports use this same evidence-first order; JSON/JUnit meanings and stored historical reports stay unchanged. Runner process failures use PROCESS_STATE when worker termination is not proved, retaining the original HAR-10 / runner-execution cause across recovery guards. Private process-state diagnostics distinguish live tasks from Linux zombies; permission/read errors stay unknown. Docker and native Kubernetes entrypoints use the bundled Tini subreaper without changing Pod privileges. For legacy unfinished sessions, only the retained account's exact terminal Kubernetes run/Job/Pod/container and current node identity can attest termination against the unchanged session. This does not update old results or replace UID/revision-bound cleanup and independent resource absence checks. No new API endpoint or service-account permission is added. The start dialog selects one or more P0 phases (0–8, all by default) through the shared start API. The API validates and sorts the immutable selection; the existing operator passes it to the Kubernetes runner. Subset runs keep automatic cleanup and baseline checks, and show only their selected-phase progress/results. An optional immutable diagnosticSelection selects a fixed Phase 2, 3, 4 or 5 subset from the Git-owned regression catalog. The API advertises profiles only for a qualified runner; the operator rechecks catalog, phase, pins and capability before creating its Job. Distinct credential readiness and a diagnostic entrypoint fail closed during mixed-version upgrades. The native runner discovers exact registered scenario IDs and reuses the serial launcher for phase2-models, phase3-validation or phase4-sharing, or the separate services mode, not an arbitrary script or an all-phase fallback. Reports retain the diagnostic scope and do not grant full-phase acceptance. The fixed ollama-two-card-split profile selects only the existing Phase 4 MGPU-01 / p4-multigpu-ollama-2 A/E/O evidence, distinct from four-card split or independent copies. Product-service/application live workflows are currently deferred in ordinary runs, including service credentials and app ACLs. The explicit services profile requires runner capability 3 and discovers every applicable catalog entry/stage before execution: installation/removal, then access with SSO and supported public access. Model integration stays deferred. Capability 2 continues to offer the existing Phase 2–4 profiles but never advertises the new service profile. Pi Coding Agent is included; Hermes remains separate. Exact runtime UID receipts verify removal before restoring a borrowed service; unknown writes stay fenced. The shared source policy governs selected live layers, input preparation and workflow dispatch; isolated contracts and core user/license/Kubernetes/model/GPU checks stay selected. MOD-06 uses its own GPU-profile prerequisite. Reports record the exclusion without rewriting older results or skipping old cleanup. The dialog also selects testMode: non-destructive by default, or full including destructive scenarios. The API stores the immutable choice. Non-destructive Jobs receive only a fresh viewer account and report-store mount; no old private inputs or recovery journals. They bypass mutating setup/cleanup and select only reviewed isolated suites plus the GET-only live inventory adapter. Reports explicitly name excluded steps and cannot certify full phase acceptance. Legacy omitted modes remain full; clients must never retry a rejected safe-mode request as full. Enabling, registering, starting, cancelling and downloading reports are core functions with no license prerequisite. Test registration binds a disposable installation, not a licensing edition; keep license queries out of that control path. License/SSO scenarios retain their own signed-fixture/entitlement checks. Full GPU scenarios support both saved sharing settings and a fresh exclusive installation with no sharing intent. The shared restoreDefaults contract can remove only previously unset sharing/validation fields after the controller has restored exclusive Device-plugin readiness. UID/generation-bound journals retain the exact absent/empty representation and unrelated module parameters; an unacknowledged write is not adopted. Safe-mode runs never use this mutation. Provider Secrets created from user-entered model credentials must stay scoped to that dashboard workflow. Keep dashboard examples limited to example.local, example.com, CHANGEME, or documented variables.

The standard React frontend and terminal clients live under dashboard/. Deployment resources and the shared API remain in magic-cluster/apps/dashboard; there is no separate preview frontend or ConfigMap-based HTML renderer. All clients share framework-neutral contracts, transport, and core logic. Install and verify them with the pinned workspace lockfile:

cd dashboard
corepack enable
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build

pnpm build creates both the React bundle and the standalone apps/cli/dist/magicstick.js executable. Smoke-test the CLI without a live server:

pnpm cli --version
pnpm cli --help

The final CLI image uses Alpine's Node 24 package and copies only the bundled executable and license notices from the build inputs. No npm, npx or workspace dependencies are installed or inherited in the final image. The image build also checks the bundle's source map for Picomatch. On Linux AMD64 and ARM64 it checks the launch path and runs --version and --help without network access as the same non-root user as the console. Inspect each published platform's SBOM separately from the workspace dependency audit.

Build production images from the repository root (not dashboard/) so source-of-truth license notices can be included:

cd .. # when still in dashboard/ from the commands above
docker build -f dashboard/apps/web/Dockerfile -t magicstick-dashboard:local .
docker build -f dashboard/apps/cli/Dockerfile -t magicstick-cli:local .
docker build -f dashboard/apps/api/Dockerfile -t magicstick-api:local .

The dashboard nginx configuration and the identity auth-pilot use one worker, matching their fractional CPU budgets. Do not scale their workers to the host's CPU count: that can exceed the Pod's memory limit on a many-core appliance. The pilot mounts a hash-named generated ConfigMap, so configuration changes roll its Pod. Keep the existing CPU/RAM limits and the dashboard's non-root, read-only runtime. CI runs both nginx configurations inside their declared resource budgets:

MAGICSTICK_RUN_NGINX_CONTAINER_TESTS=1 python3 -m unittest -v tests.test_nginx_runtime

The tests check HTTP responses, exactly one worker, no cgroup OOM events and no container restarts; they need Docker and no appliance access. The dashboard nginx retains four on-demand 16 KiB large-header buffers. Each individual field must fit one buffer; the synthetic header tests verify both accepted and rejected sizes without storing credentials. They test header parsing, not authentication, and retain the existing 128 MiB non-root runtime budget. Host-only cookie migration and OIDC/logout checks remain separate identity acceptance gates.

The API Dockerfile has one final runtime containing the BSL-licensed magicstick_core package, license texts and third-party notices. Only Federated SSO depends on a signed entitlement. Do not split the source or images by edition. Follow the release audit before publishing.

For coordinated API/ConfigMap changes, matching immutable images must publish before deployment pins advance. Normal main builds propose a coordinated pin PR only after public, browser and native publishing checks succeed. The workflow can also build an integration branch via workflow_dispatch, but does not automatically promote manual candidates. Main builds may update mutable web, react-preview, console and api-licensing-v1 discovery aliases. Integration branches publish SHA tags without moving the integration trunk or a fixed product version. Aliases alone never change a pinned Deployment. See image promotion.

Software channel selection extends the existing host-operation contract rather than creating another update controller. software_contract.py is shared by the API image and host worker. SoftwareChannelEditor uses typed host status and the administrator-only release catalog; verified stable/prerelease versions are separate from development refs. release_catalog.py shares strict product, immutable-manifest and per-version license validation with host/installer/tools. check/apply requests; the host performs Git/registry inspection, Ansible execution, Flux verification and durable recovery. Tests cover role enforcement, ref syntax, stale previews, moved branches, failure pause and matching image verification. Keep Ubuntu package policy separate. See API contract.

The browser and terminal apps may import only packages/api-client, packages/contracts, and packages/core for control-plane behavior. Keep DOM, React, ANSI, filesystem, and process dependencies out of those packages. New API capabilities must be implemented and authorized in the shared dashboard API, not directly against Kubernetes from any client. CLI mutations should use explicit commands. The TUI uses role-filtered controls and tested confirmation dialogs for mutations; it must not bypass shared API authorization.