Admin dashboard

Overview

The KavachOS dashboard is a visual interface for everything the SDK manages through code: creating and revoking agents, reviewing audit logs, inspecting delegation chains, and monitoring permissions.

It is optional. You can use the SDK entirely through code without the dashboard.

It ships in two forms:

1. A React component (@kavachos/dashboard) you embed in an existing app
2. A standalone CLI server you run without any frontend code

Quick start (demo mode)

The fastest way to see the dashboard in action:

npx kavachos dashboard

This starts a full KavachOS instance with in-memory SQLite, seeds sample data (3 agents, permissions, audit entries, a delegation chain), and serves the dashboard on http://localhost:3100.

To add a login screen:

KAVACHOS_DASHBOARD_SECRET=your-secret npx kavachos dashboard

When KAVACHOS_DASHBOARD_SECRET is set, the dashboard shows a password prompt before granting access. Without it, the dashboard is open (suitable for local development only).

Installation

pnpm add @kavachos/dashboard

import { KavachDashboard } from '@kavachos/dashboard';

export default function AdminPage() {
  return (
    <KavachDashboard
      apiUrl="/api/kavach"
      theme="system"
      demo={false}
    />
  );
}

// app/api/kavach/[...path]/route.ts
import { createKavach } from 'kavachos';
import { kavachNextjs } from '@kavachos/nextjs';

const kavach = await createKavach({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
});

const handler = kavachNextjs(kavach);
export const GET = handler;
export const POST = handler;
export const DELETE = handler;
export const PATCH = handler;

import { Hono } from 'hono';
import { createKavach } from 'kavachos';
import { kavachHono } from '@kavachos/hono';

const kavach = await createKavach({
  database: { provider: 'sqlite', url: 'kavach.db' },
});

const app = new Hono();
app.route('/api/kavach', kavachHono(kavach));

import express from 'express';
import { createKavach } from 'kavachos';
import { kavachExpress } from '@kavachos/express';

const kavach = await createKavach({
  database: { provider: 'sqlite', url: 'kavach.db' },
});

const app = express();
app.use('/api/kavach', kavachExpress(kavach));

// app/admin/page.tsx
import { redirect } from 'next/navigation';
import { getSession } from '@/lib/auth';
import { KavachDashboard } from '@kavachos/dashboard';

export default async function AdminPage() {
  const session = await getSession();
  if (!session?.user.isAdmin) redirect('/');

  return <KavachDashboard apiUrl="/api/kavach" theme="system" />;
}

npx kavachos dashboard --port 3100

KAVACHOS_DASHBOARD_SECRET=my-admin-password npx kavachos dashboard --port 3100

Dashboard pages

The dashboard has nine pages accessible from the sidebar.

Overview: Active agent count, authorization rate (allowed vs denied), recent audit entries with live refresh, and quick action buttons.

Agents: List all agents with status badges. Create new agents with initial permissions, rotate tokens, and revoke agents. Click an agent to see its permissions, recent audit entries, and delegation chains.

Users: List human users who own agents, with agent counts.

Permissions: Create and manage permission templates. Templates let you define a permission set once and apply it to multiple agents. Supports visual and raw JSON editing modes.

Delegations: View all active delegation chains. Shows the from/to agents, delegated permissions, depth, and expiry countdown.

MCP Servers: Register MCP servers with their endpoints, tools, and auth requirements. Monitor status and token validation activity.

Audit Log: Full queryable log of every authorization decision. Filter by agent, action, resource, result, and date range. Export as JSON or CSV for compliance.

Security: Security-focused view showing rate-limited agents, recent denials, revoked agents, and expired tokens.

Settings: Database connection info, token expiry policy, rate limit defaults, and audit retention settings.

Light and dark mode

The dashboard supports both light and dark themes. A toggle button in the top-right header switches between them. The preference is saved to localStorage and persists across sessions.

When embedded as a React component, pass theme="light", theme="dark", or theme="system" to set the initial mode.

API endpoints

The dashboard calls these REST endpoints on your backend. If you are building a custom dashboard or integrating with other tools, here is the full list: