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.