\n\n# @swiss-ai-hub/web\n\n**The admin and management UI for [Swiss AI Hub](https://github.com/bbvch-ai/aihub-core), published as a\n[Nuxt 3 layer](https://nuxt.com/docs/getting-started/layers).**\n\n[](https://www.npmjs.com/package/@swiss-ai-hub/web)\n[](https://github.com/bbvch-ai/aihub-core/blob/main/packages/web/LICENSE)\n\n
\n\n______________________________________________________________________\n\n## What is Swiss AI Hub?\n\n[Swiss AI Hub](https://github.com/bbvch-ai/aihub-core) is an open-source, self-hosted AI platform for enterprises. One\n`docker compose up` starts ~30 integrated containers: an LLM gateway (LiteLLM), vector search (Milvus), data pipelines\n(Dagster), document parsing (MinerU), SSO (Keycloak), observability (Langfuse + OpenTelemetry), a chat UI (Open-WebUI),\nand more. You build custom agents, pipelines, and processes using the Python SDK; the platform provides the runtime.\n\n## What is this package?\n\nThis package is the **admin and management UI** -- one component of the larger platform. It is the interface where\nadministrators configure agents, manage knowledge bases, monitor processes, inspect threads, assign roles, track costs,\nand build dashboards. It is **not** the chat UI (that's [Open-WebUI](https://github.com/open-webui/open-webui)) and not\nthe backend API.\n\nThe admin UI is built with [Nuxt 3](https://nuxt.com/), [Vue 3](https://vuejs.org/), [PrimeVue](https://primevue.org/),\nand [Tailwind CSS](https://tailwindcss.com/). It is published as a\n**[Nuxt layer](https://nuxt.com/docs/getting-started/layers)** -- a mechanism that lets you inherit an entire Nuxt\napplication (pages, components, composables, plugins, config) and extend or override any part of it in your own project.\n\n______________________________________________________________________\n\n## Should you use this package?\n\n**Probably not.** Most deployments should use the pre-built Docker image, which ships the admin UI ready to go:\n\n```yaml\n# docker-compose.yml\nservices:\n admin-ui:\n image: ghcr.io/bbvch-ai/aihub-core/web:latest\n ports:\n - \"3333:80\"\n```\n\nThe Docker image works out of the box with zero frontend code. Configuration (OIDC provider, API endpoint, WebSocket\nURL) is handled through environment variables at runtime.\n\n**Use this npm package only if you need to extend the UI with your own code** -- adding custom pages, overriding\ncomponents, modifying translations, or changing the theme. This is an SDK for building a custom frontend on top of Swiss\nSwiss AI Hub, not a standalone app.\n\n## When this package makes sense\n\n| Use case | Example |\n| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |\n| **Custom pages** | Add an organization-specific dashboard, a domain-specific tool, or internal admin views that don't belong in the open-source project |\n| **Branding** | Override the PrimeVue theme, replace the logo, adjust colors to match corporate identity |\n| **Translation overrides** | Fix or extend translations, add a fifth language, change terminology to match your domain |\n| **Component overrides** | Replace a built-in component with your own implementation |\n| **Custom plugins** | Add organization-specific Nuxt plugins (analytics, feature flags, custom error tracking) |\n| **Custom auth flow** | Extend the OIDC middleware for provider-specific requirements |\n\n______________________________________________________________________\n\n## How Nuxt layers work\n\nIf you're not familiar with [Nuxt layers](https://nuxt.com/docs/getting-started/layers), here's the idea: a layer is a\nfull Nuxt application that another Nuxt project can inherit from using `extends` in `nuxt.config.ts`. When you extend\nthis layer, you get all of its pages, components, composables, plugins, middleware, layouts, and configuration -- merged\ninto your project automatically. Nuxt resolves conflicts by giving your project priority: if you define a component with\nthe same name and path as one in the layer, yours wins. Same for pages, composables, and config keys.\n\nThis means you don't fork the repo or copy files. You install the package, extend it, and only write the code for what\nyou want to change or add.\n\nFor a deeper understanding, see the [official Nuxt layers documentation](https://nuxt.com/docs/getting-started/layers)\nand the [layer authoring guide](https://nuxt.com/docs/guide/going-further/layers).\n\n______________________________________________________________________\n\n## Installation\n\n```bash\nnpm install @swiss-ai-hub/web\n# or\npnpm add @swiss-ai-hub/web\n```\n\nInstall the required peer dependencies:\n\n```bash\nnpm install primevue@4.5.5 vue@3.5.17\n```\n\n### Required dependency overrides\n\n**Do not skip this step.** Without it your project ends up with two copies of Vue in `node_modules`, and the UI will\neither fail to build or render with broken behavior.\n\nNuxt and several of its modules depend on their own (newer) copy of Vue, while this layer is built and tested against an\nexact Vue version. With nothing forcing them to agree, your install resolves **two different Vue versions** -- and\ntherefore two copies of `@vue/runtime-core`, the package that owns Vue's runtime identity. Two Vue runtimes means two\nseparate reactivity systems: `provide`/`inject` stops working across the boundary, component instance checks fail, and\nyou get cryptic errors like _\"Vue instance ... was created in a different application\"_. The same single-instance\nrequirement applies to PrimeVue, whose theme system relies on a global singleton (two instances → unstyled components).\n\nThe fix is to force the whole dependency tree onto one Vue version using your package manager's override mechanism. Add\nthe **`vue`** override to your project's `package.json` — this is the one that actually breaks if omitted. Note the key\ndiffers per package manager (npm/pnpm use `overrides`, Yarn uses `resolutions`):\n\n```jsonc\n// npm\n{ \"overrides\": { \"vue\": \"3.5.17\" } }\n```\n\n```jsonc\n// Yarn\n{ \"resolutions\": { \"vue\": \"3.5.17\" } }\n```\n\n```jsonc\n// pnpm\n{ \"pnpm\": { \"overrides\": { \"vue\": \"3.5.17\" } } }\n```\n\nThen reinstall from a clean state so the lockfile is regenerated, and confirm a single Vue instance:\n\n```bash\nrm -rf node_modules package-lock.json # or yarn.lock / pnpm-lock.yaml\nnpm install\nnpm ls @vue/runtime-core # must print exactly one version: 3.5.17\n```\n\nThe same single-instance requirement applies to **PrimeVue** (its theme system is a global singleton); pinning the\n`primevue` peer to one version is enough — it does not need an override.\n\n> **Important — pin `vue-router` so `@vueuse/router` uses Nuxt's router.** `@vueuse/router` declares a `vue-router` peer\n> whose range also accepts `vue-router` 5.x, which some transitive deps (e.g. `@nuxtjs/i18n` / `unplugin-vue-router`)\n> legitimately pull in. If `@vueuse/router` resolves to that 5.x copy while the Nuxt app runs `vue-router` 4.x, the two\n> use **different injection keys**: `useRouter()` returns `undefined` inside `@vueuse/router`, and `useRouteQuery` then\n> throws `TypeError: Invalid value used as weak map key` (notably inside Pinia-Colada `defineQuery` setups, which run\n> outside component inject context). This is **not** harmless — it white-screens the affected pages.\n>\n> pnpm `overrides` do **not** constrain peerDependency resolution, so a `@vueuse/router>vue-router` override is not\n> enough (it silently stops working the moment a higher `vue-router` lands in range). Pin it reliably by declaring\n> `vue-router` as a **direct dependency** of your app package at the version Nuxt uses — the peer then binds to that\n> copy, while the other major can remain for `@nuxtjs/i18n`:\n>\n> ```jsonc\n> // packages/web/package.json\n> { \"dependencies\": { \"vue-router\": \"4.6.4\" } }\n> ```\n>\n> Verify with `pnpm why vue-router` (`@vueuse/router` must show `4.6.4`) and `pnpm build` (`nuxt generate` must succeed\n> — forcing a single `vue-router` major instead breaks `@nuxtjs/i18n`, which needs 5.x).\n\n## Quick start\n\n### 1. Create a Nuxt project\n\n```bash\nnpx nuxi init my-aihub-frontend\ncd my-aihub-frontend\nnpm install\n```\n\nThen install this package, its peer dependencies, and -- importantly -- add the\n[required dependency overrides](#required-dependency-overrides). Skipping the overrides leaves two copies of Vue in your\ntree and the app will not work.\n\n### 2. Extend the layer\n\nReplace the generated `nuxt.config.ts` with:\n\n```ts\n// nuxt.config.ts\nexport default defineNuxtConfig({\n extends: ['@swiss-ai-hub/web'],\n\n // These dev defaults match infra/docker-compose.dev.yml + `make run-api`.\n // For production, leave these declared (the keys must exist) but blank, and\n // inject values at runtime via /config.js -- see Runtime configuration below.\n runtimeConfig: {\n public: {\n env: 'dev',\n oidc: {\n clientId: 'aihub-frontend',\n authorityUrl: 'http://localhost:8180/realms/aihub',\n },\n webui: {\n url: 'http://localhost:8080',\n },\n ws: {\n endpoint: 'ws://localhost:8000/api/v1/active/events/ws',\n },\n },\n },\n\n // Proxy API requests to the backend during development.\n // In production, your reverse proxy (Traefik) handles this.\n nitro: {\n devProxy: {\n '/api/v1': {\n target: 'http://localhost:8000/api/v1',\n changeOrigin: true,\n ws: true,\n },\n },\n },\n})\n```\n\n### 3. Start the platform\n\nMake sure the Swiss AI Hub backend is running (either via `docker compose up` or locally with `make run-api`).\n\n### 4. Run\n\n```bash\nnpx nuxi dev\n```\n\nOpen `http://localhost:3000`. You get the full admin UI -- agents, processes, threads, knowledge bases, models, roles,\ndashboards, and chat -- running locally and pointing at your platform instance. Log in with your Keycloak credentials\n(default: `admin` / `admin`).\n\n______________________________________________________________________\n\n## What the layer provides\n\nEverything the admin UI needs ships inside this package:\n\n| Category | What you get |\n| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |\n| **Pages** | Full file-based routing under `/service/` -- agents, processes, threads, knowledge, models, roles, dashboards, chat, costs, evaluations |\n| **Components** | ~170 Vue components organized by domain (Agent, Chat, Dashboard, Event, Navigation, Process, Thread, Workflow, ...) |\n| **Composables** | [Pinia-Colada](https://pinia-colada.esm.dev/) query/mutation wrappers for every API resource |\n| **SDK client** | Auto-generated TypeScript API client ([HeyAPI](https://heyapi.dev/)) |\n| **Layouts** | `default` (authenticated) and `anonymous` layouts |\n| **Middleware** | OIDC auth guard on all routes |\n| **Plugins** | OIDC client, config loader, ApexCharts |\n| **i18n** | German, English, French, Italian (lazy-loaded YAML files) |\n| **Theme** | PrimeVue [Aura](https://primevue.org/theming/styled/#aura)-based theme with dark mode support |\n| **FormKit config** | Custom form inputs (agent selector, model select, knowledge database selector, icon selector, locale input, vector store input) |\n\n______________________________________________________________________\n\n## Extending the UI\n\n### Add a custom page\n\nCreate a Vue file in `pages/` and Nuxt merges it with the layer's routes. The layer's components and composables are\nauto-imported and available in your pages without any explicit imports:\n\n```vue\n\n\n \n \n
This page lives only in your deployment, not in the open-source project.
\n
All layer components and composables are available here.
\n \n \n\n```\n\n`StructuralScreen` is the full-height scrollable container used by every page. `StructuralColumn` provides a titled\npanel with built-in loading states -- pass `:loading=\"true\"` to show a progress bar and suppress content until data is\nready. These are the two layout primitives that all admin UI pages are built on.\n\nTo add navigation for your page, you can extend the sidebar by overriding the navigation component (see\n[Override a component](#override-a-component) below).\n\n### Override translations\n\nThe layer ships i18n files for German, English, French, and Italian in `i18n/locales/`. To override specific keys or add\na new language, create matching locale files in your project:\n\n```\nmy-project/\n i18n/\n locales/\n en.yaml # keys here override the layer's en.yaml\n de.yaml\n pt.yaml # add a new language\n```\n\n```yaml\n# i18n/locales/en.yaml -- only the keys you want to change\nagent:\n title: \"AI Assistants\" # override \"Agents\" with your preferred term\nmy_tool:\n title: \"My Custom Tool\" # add keys for your custom pages\n```\n\nYou also need to register new languages in your `nuxt.config.ts`:\n\n```ts\nexport default defineNuxtConfig({\n extends: ['@swiss-ai-hub/web'],\n\n i18n: {\n locales: [\n { code: 'pt', file: 'pt.yaml', name: 'Portugues' },\n ],\n },\n})\n```\n\n### Override the theme\n\nThe admin UI uses [PrimeVue's styled mode](https://primevue.org/theming/styled/) with a customized\n[Aura preset](https://primevue.org/theming/styled/#aura). Theming works through **design tokens** -- semantic color\nvalues that PrimeVue components reference. You override tokens to change the look of every component at once.\n\nTo create your own theme, start from the Aura preset and customize the tokens you want to change:\n\n```ts\n// themes/my-theme.ts\nimport { definePreset } from '@primeuix/themes'\nimport Aura from '@primeuix/themes/aura'\n\nconst MyPreset = definePreset(Aura, {\n semantic: {\n // Change the primary color palette (used for buttons, selections, highlights)\n primary: {\n 50: '#eff6ff',\n 100: '#dbeafe',\n 200: '#bfdbfe',\n 300: '#93c5fd',\n 400: '#60a5fa',\n 500: '#3b82f6',\n 600: '#2563eb',\n 700: '#1d4ed8',\n 800: '#1e40af',\n 900: '#1e3a8a',\n 950: '#172554',\n },\n // Override light/dark mode colors\n colorScheme: {\n light: {\n primary: {\n color: '#2563eb',\n inverseColor: '#ffffff',\n hoverColor: '#1d4ed8',\n activeColor: '#1e40af',\n },\n },\n dark: {\n primary: {\n color: '#60a5fa',\n inverseColor: '#172554',\n hoverColor: '#93c5fd',\n activeColor: '#bfdbfe',\n },\n },\n },\n },\n})\n\nexport default {\n preset: MyPreset,\n options: {\n darkModeSelector: '.dark', // must stay '.dark' to match the Tailwind dark mode config\n },\n}\n```\n\nThen point your `nuxt.config.ts` at it:\n\n```ts\n// nuxt.config.ts\nimport { fileURLToPath } from 'url'\n\nexport default defineNuxtConfig({\n extends: ['@swiss-ai-hub/web'],\n\n primevue: {\n importTheme: {\n from: fileURLToPath(new URL('./themes/my-theme.ts', import.meta.url)),\n },\n },\n})\n```\n\nFor the full list of design tokens you can customize, see the\n[PrimeVue theming documentation](https://primevue.org/theming/styled/) and the\n[Aura preset reference](https://primevue.org/theming/styled/#aura).\n\n### Override a component\n\nNuxt's layer system resolves components by name and directory path. If you place a component with the same name in the\nsame directory structure, your version takes priority over the layer's:\n\n```\nmy-project/\n components/\n Navigation/\n Logo.vue # replaces the layer's Navigation/Logo.vue\n Agent/\n Card.vue # replaces the layer's Agent/Card.vue\n```\n\nThis works for any component in the layer. You can inspect the layer's component directory structure in the\n[source repository](https://github.com/bbvch-ai/aihub-core/tree/main/packages/web/components) to find the exact names\nand paths.\n\n______________________________________________________________________\n\n## Building for production\n\n```bash\nnpx nuxi generate\n```\n\nThis produces a fully static SPA in `.output/public/` (the layer is client-only -- `ssr: false`). Because the output is\nstatic, there is **no Node server at runtime to read environment variables**. Instead, the layer ships a small\nruntime-config mechanism (see [Runtime configuration](#runtime-configuration)) so you build **one** image and configure\nit per environment at container start -- including which backend API it talks to.\n\n### Dockerfile example\n\nThis mirrors how Swiss AI Hub ships the admin UI: build the static site, serve it with nginx, and generate `/config.js`\nfrom a template at startup so the same image works in any environment.\n\n```dockerfile\n# 1. Build the static SPA. ENV must be unset (or anything other than 'dev') so\n# the layer emits the