Beacon — local web dashboard

Beacon is the local web dashboard for your Vault. It’s a single-page application built on React 19 + Vite 6 + Tailwind 4 + TypeScript 5.8, embedded inside the korva-vault binary at release time (-tags embedui). Visit http://localhost:7437 while the vault is running and there it is — no extra port, no extra process.

Architecture

The same korva-vault binary serves:

• MCP over stdio (for AI clients).
• REST API at /api/v1/* (for the CLI and external tooling).
• The SPA at / and any nested route (with proper SPA routing fallback to index.html).

In dev mode (npm run dev in beacon/), the SPA runs on port 5173 and proxies API calls to http://localhost:7437/vault-api/*. Production builds bake the SPA into the binary so there’s nothing extra to deploy.

Routes

/                         → Marketing landing (public)
/admin/*                  → Admin panel (requires admin.key)
  /admin/dashboard        → System KPIs
  /admin/vault            → Vault Browser (search + delete)
  /admin/scrolls          → Public Scrolls
  /admin/scrolls-private  → Private Scrolls (Teams+)
  /admin/teams            → Teams + members + invites (Teams+)
  /admin/skills           → Skills Hub with versioning (Teams+)
  /admin/audit            → Audit log (Teams+)
  /admin/code-health      → SDD quality gates
  /admin/license          → Activation / status

/app/*                    → User dashboard
  /app/overview           → Vault stats
  /app/vault              → Vault Explorer (search obs)
  /app/sessions           → Session history
  /app/lore               → Lore Manager
  /app/settings           → Preferences

Authentication

The admin panel login (/admin) offers two authentication methods — switch between them with the tab at the top of the login form:

Both credentials are validated against the vault and stored in sessionStorage only (cleared when the tab closes). Maximum 5 failed attempts, 30-second lockout on the sixth.

Shared vault deployments — when you run a single korva-vault instance for the whole team (e.g. vault.yourcompany.com), only the person who set up the server has the admin key. Any other team admin can still access the panel by logging in with their session token — no need to share the server’s key.

• Teams gate — <TeamsGate> wraps Teams-only features and verifies useLicenseStatus().tier.

i18n

Beacon ships with full English and Spanish support: navigation, common words, auth flows, license, dashboard, vault, scrolls, private scrolls, teams, skills, audit, code health, editor, glossary. Hook: useI18n() exposes { lang, setLang, t, editor, setEditor }. Persisted in localStorage (korva-lang, korva-editor).

Stack

Design system

Typography: Syne (display), IBM Plex Sans (body), JetBrains Mono / Fira Code (code).

Building Beacon yourself

make beacon-dev          # Vite dev server on :5173
make beacon-build        # full prod build → beacon/dist
make vault-full          # Beacon build + Go build with -tags embedui

The vault-full target is what release engineering runs to produce the shipping binary.

Tests

7+ test files in beacon/src/__tests__/:

• AdminLogin.test.tsx — render, submit, validation, lockout
• ErrorBoundary.test.tsx, Glossary.test.tsx, InfoCallout.test.tsx, PageHeader.test.tsx
• adminStore.test.ts — Zustand mutations + persistence
• i18n.test.ts — language switching + translation completeness

Coverage report: v8 (--coverage), HTML + text output.

Why a local dashboard?

The CLI is fast for power users; Beacon is for the rest of the team. Writing scrolls, browsing the timeline, redeeming invites, managing skills — these are all easier in a UI. Crucially, since Beacon ships inside the binary, you don’t need a separate deployment to expose it.

Next

• Self-hosting — when you want Beacon reachable from the rest of the team
• Teams admin — Beacon’s Teams-tier features