Console

The ViteHub Console is a read-only app for inspecting discovered Agents and retained Agent Invocations. It is off by default. Enable it, start the app, then open /_vitehub to browse sessions, search retained text, and inspect invocation events.

Console data can contain user prompts, model output, tool activity, and provider metadata. Protect the Console before making it reachable on a production URL.

Enable the Console

Set console: true in the root ViteHub integration. The Node preset supports the Console in development and production.

import { vitehub } from 'vite-hub'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [vitehub({
    agent: true,
    console: true,
    preset: 'node',
  })],
})

A standalone Nitro 3 app adds Nitro after ViteHub. The Console app and its UI dependencies ship inside vite-hub, so an existing Nitro app does not need another Console or UI package.

import { nitro } from 'nitro/vite'
import { vitehub } from 'vite-hub'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vitehub({
      agent: true,
      console: true,
      preset: 'node',
    }),
    nitro(),
  ],
})

Nuxt uses the same option. Install Nuxt UI because the Console uses the ViteHub UI module.

pnpm add @nuxt/ui

import viteHubNuxt from 'vite-hub/nuxt'

export default defineNuxtConfig({
  modules: [
    [viteHubNuxt, {
      agent: true,
      console: true,
      preset: 'node',
    }],
  ],
})

Restart the development server after changing the option. Open http://localhost:3000/_vitehub, using your app's actual origin and port.

If console is omitted or set to false, ViteHub does not register a Console page, API handler, Nitro plugin, or public asset path. A disabled Console returns the host's normal not-found response.

Protect both route groups

console: true registers the page under /_vitehub/** and its read API under /api/_vitehub/console/**. It does not add authentication or an admin role.

If the app uses ViteHub Auth, guard both route groups in the Primary Auth Definition. The host decides what makes a user an administrator.

import { defineAuth, type AuthAccessAuthorize } from 'vite-hub/auth'

const authorizeConsole: AuthAccessAuthorize = ({ user }) =>
  user.role === 'admin'

export default defineAuth({
  access: {
    routes: [
      { route: '/_vitehub/**', authorize: authorizeConsole },
      { route: '/api/_vitehub/console/**', authorize: authorizeConsole },
    ],
  },
})

ViteHub checks for an Auth Session before it calls authorizeConsole. A missing session returns 401. Returning false from the callback returns 403. The callback can return a Response when the app needs another rejection or redirect.

The role field above is an application example, not a ViteHub field. Replace it with the role, permission, or allowlist already used by the host. Apps that use another authentication library should protect the same two route groups in host middleware.

Read Auth for sign-in redirects and the complete callback contract.

Know what the Console stores

The Console installs a fallback Agent Invocation journal at .vitehub/data/console.sqlite. It retains invocation records and selected searchable text, including prompts, messages, final text, and progress updates.

The journal has no automatic TTL or deletion. In production, the operator must define how long to retain the file and how to remove records that may contain sensitive data.

The fallback applies only when an Agent Definition does not configure invocations. An explicit defineAgent({ invocations }) store remains authoritative, and its sessions are not copied into console.sqlite or read by the built-in Console.

The automatic fallback also requires defineAgent from vite-hub/agent. Definitions imported directly from @vite-hub/agent must configure their own invocations store. Use the Invocation UI with that store when the app needs a custom inspection page.

Production Console builds currently require preset: 'node' because the fallback journal uses local SQLite. The Node preset supports the build, but it does not make .vitehub/data/console.sqlite persistent: the host must provide durable storage that survives process and deployment replacement. The file is also local to one replica and is not shared across replicas. Other presets can run the Console during development. Their production builds fail while console: true is set, so ViteHub does not write the journal to storage that may disappear between requests or deployments.

The Console API accepts GET requests only. Responses set Cache-Control: no-store and X-Content-Type-Options: nosniff.

Inspect usage

Session details show recorded token totals when the invocation trace contains provider usage. Add the Usage Capability when the provider needs an explicit usage request or the Agent must expose the normalized Agent Usage Record at finish.

The Console does not calculate missing provider data. Token counts, model metadata, and provider-reported cost remain absent when the provider does not report them.

Fix common failures

Use Agent Invocations for custom stores and invocation lifecycle behavior. Use Invocation UI when building an application-owned inspection page instead of mounting the complete Console.