Skip to main content

nexus-ui

The Nexus Admin — the operator console for the platform. A standalone Next.js app that manages everything through the Nexus Core REST API: agents, skills, memory, the board, runs, and approvals.

It is deliberately not part of nexus-platform: the Rust monorepo stays Rust-only, and the UI ships on its own (Node) release cadence.

Stack​

ConcernLibrary
FrameworkNext.js 16 (App Router), React 19
StylingTailwind CSS v4 (token-based, dark-first)
DataTanStack Query + TanStack Table
PrimitivesRadix UI, lucide-react, sonner, cmdk, nuqs
Validationzod

How it talks to Core​

The browser never calls Nexus Core directly. Every request goes through a same-origin server route that injects the API key server-side:

Browser ──► /api/nexus/[...path]   (Next.js route handler, nodejs runtime)
                 │  injects  X-Nexus-Api-Key  (server-only secret)
                 ▼
            Nexus Core REST API     (NEXUS_CORE_URL)

This keeps the API key out of the client bundle, gives one place to re-check the operator session and log admin actions, and avoids CORS entirely.

Layout​

src/
  app/
    (admin)/            gated route group (Dashboard, Agents, Skills,
                        Memory, Board, Runs, Approvals, Integrations,
                        Telegram, Settings)
    api/
      nexus/[...path]/  server reverse proxy to Nexus Core
      auth/             sign-in / sign-out (shared-token session)
    sign-in/            operator sign-in page
  components/
    layout/             AdminShell, AppSidebar, Breadcrumbs, header bits
    ui/                 button, card, badge, input, table, … (shadcn-style)
    kpi/                dashboard KPI card
    providers/          React Query + theme + toaster
  lib/
    api.ts              typed browser client (hits the proxy)
    queries.ts          React Query hooks + cache keys
    types.ts            Core API type shapes (mirror nexus-domain)
    auth.ts             shared-token sign-in + HMAC session cookie
    env.ts              zod-validated server env
    format.ts, cn.ts    formatting + class helpers
  middleware.ts         edge gate (cookie presence)

Auth (v1)​

An operator signs in at /sign-in with NEXUS_ADMIN_TOKEN. On success the server sets an httpOnly cookie whose value is an HMAC of a fixed marker keyed by AUTH_SECRET — the token itself never lands in a cookie. The gated (admin) layout verifies the cookie (server-side, node:crypto) and the proxy re-checks it. Swap in OIDC/Keycloak or Core-issued JWTs later without changing call sites.

Environment​

VarScopePurpose
NEXUS_CORE_URLserverBase URL of the Nexus Core REST API
NEXUS_API_KEYserverSent upstream as X-Nexus-Api-Key
NEXUS_ADMIN_TOKENserverOperator sign-in token
AUTH_SECRETserverDerives the session cookie
NEXT_PUBLIC_APP_NAMEclientDisplay name