Norns Admin

Web interface for interacting with Norns AI agents.

---

Overview

Norns Admin is a Next.js application providing chat UI, voice calls, document management, and admin features.

Property	Value
Container	norns-admin
URL	norns.ravenhelm.dev
Port	3000 (internal), 3001 (external)
Source	~/ravenhelm/docs/AI-ML-Platform/norns-agent/admin/
Repo	gitlab.ravenhelm.dev/ravenmask/norns-admin

---

Features

Feature	Description	Route
Chat Interface	Conversational AI with orchestration visualization	/chat
Voice Chat	LiveKit-powered voice calls	/voice
Sessions	View all user sessions with transcripts	/sessions
Knowledge Base	Manage documents and memories	/knowledge
Documents	Upload files, crawl web content, view chunk details	/documents
Tools	Manage Bifrost tools and configurations	/tools
Calls	View call history and manage campaigns	/calls
Profile	User identity, preferences, insights	/profile
Settings	Configuration and preferences	/settings

---

Documents Page

Document management interface with chunk viewing.

Features

Feature	Description
File Upload	Drag-and-drop or click to upload documents
Web Crawling	Scrape single pages or crawl entire sites
Document List	View all ingested documents with chunk counts
Chunk Viewer	Click any document to view its content chunks
Metadata Display	See token counts, content types, and source info

Document Detail Modal

Click on any document card to open the detail modal showing:

• Document metadata (name, type, source URL)
• List of all chunks with:
  • Chunk index and token count
  • Full chunk content (expandable)
  • Content type indicator
  • Associated metadata

---

Calls & Campaigns

Telephony management interface for outbound campaigns.

Call History

View all AI voice calls with:

• Call status (completed, failed, in-progress)
• Duration and timestamps
• Recipient information
• Transcript access

Campaigns

Create and manage outbound calling campaigns:

• Campaign creation wizard
• Recipient list management
• Campaign status monitoring
• Bulk recipient import

Routes

Route	Description
/calls	Call history list
/calls/new	Initiate new call
/calls/campaigns	Campaign list
/calls/campaigns/new	Create campaign
/calls/campaigns/[id]	Campaign details
/calls/campaigns/[id]/add-recipients	Add recipients

---

Chat Enhancements

Orchestration Timeline

Visual representation of agent workflow execution:

• Step-by-step execution path
• Tool calls and responses
• Memory retrievals
• Decision points

Memory Recall

View retrieved context during conversations:

• Knowledge base matches
• Previous conversation context
• User profile information

Task Sidebar

Manage tasks created during conversations:

• Real-time task creation
• Status updates
• Task completion tracking

---

Tools Management

Interface for managing Bifrost tools:

Route	Description
/tools	List all available tools
/tools/[id]	Tool configuration and testing

---

RBAC System

Role-based access control for admin features.

Components

Component	Description
PermissionGate	Conditionally render based on permissions
RoleGate	Conditionally render based on roles
PermissionProvider	Context provider for permission state

Usage

import { PermissionGate } from '@/lib/rbac';

<PermissionGate permission="admin:calls:manage">
  <CampaignManagement />
</PermissionGate>

---

Sessions Admin Page

Real-time session monitoring and debugging interface.

Access

Navigate to norns.ravenhelm.dev/sessions

Features

Feature	Description
Session List	View all sessions across all users and channels
Channel Filtering	Filter by slack, web, voice, or siri
Status Filtering	Filter active vs completed sessions
User Search	Search by user name or email
Live Transcript	Real-time message updates via SSE
Langfuse Traces	Embedded trace visualization for debugging

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  /sessions (Admin Page)                                          │
├─────────────────────────────────────────────────────────────────┤
│  Session List Panel          │  Session Detail Panel            │
│  ├─ Filter by channel        │  ├─ Metadata header              │
│  ├─ Filter by status         │  ├─ Transcript tab               │
│  ├─ Search by user           │  │   └─ SSE real-time updates    │
│  └─ Session cards            │  └─ Trace tab                    │
│      └─ Click to select      │      └─ Langfuse iframe          │
└─────────────────────────────────────────────────────────────────┘

---

Authentication

Uses Zitadel SSO via Auth.js:

Login → Zitadel → Callback → Session

Protected vs Public Routes

Route Pattern	Auth Required
/login	No
/health	No
/api/auth/*	No
/api/voice/*	No (LiveKit auth)
/api/proxy/*	No (API key auth)
/api/bifrost/*	No (Proxy to Bifrost)
/api/telephony/*	No (Proxy to Telephony API)
All other routes	Yes

---

API Proxies

The admin app proxies requests to backend services:

Proxy Route	Target	Description
/api/proxy/[...path]	Norns Agent	General agent API
/api/bifrost/[...path]	Bifrost API	Tool gateway
/api/telephony/[...path]	Telephony API	Voice/calls

---

Quick Commands

# View logs
docker logs -f norns-admin

# Restart
docker restart norns-admin

# Rebuild
cd ~/ravenhelm/docs/AI-ML-Platform/norns-agent/admin
export NORNS_API_KEY=$(grep NORNS_API_KEY ~/ravenhelm/secrets/.env | cut -d= -f2)
export AUTH_SECRET=$(grep AUTH_SECRET ~/ravenhelm/secrets/.env | cut -d= -f2)
export AUTH_ZITADEL_CLIENT_ID=$(grep AUTH_ZITADEL_CLIENT_ID ~/ravenhelm/secrets/.env | cut -d= -f2)
export AUTH_ZITADEL_CLIENT_SECRET=$(grep AUTH_ZITADEL_CLIENT_SECRET ~/ravenhelm/secrets/.env | cut -d= -f2)
docker compose -f docker-compose.service.yml build --no-cache
docker compose -f docker-compose.service.yml up -d --force-recreate

---

Configuration

Environment Variables

environment:
  # API Access
  - NORNS_AGENT_URL=http://host.docker.internal:3901
  - NORNS_API_KEY=${NORNS_API_KEY}
  - NEXT_PUBLIC_NORNS_API_URL=http://host.docker.internal:8000

  # Auth (Zitadel)
  - AUTH_SECRET=${AUTH_SECRET}
  - AUTH_ZITADEL_ID=zitadel
  - AUTH_ZITADEL_CLIENT_ID=${AUTH_ZITADEL_CLIENT_ID}
  - AUTH_ZITADEL_CLIENT_SECRET=${AUTH_ZITADEL_CLIENT_SECRET}
  - AUTH_ZITADEL_ISSUER=https://auth.ravenhelm.dev
  - AUTH_TRUST_HOST=true

  # Voice (optional)
  - NEXT_PUBLIC_LIVEKIT_URL=wss://livekit.ravenhelm.dev
  - VOICE_API_URL=http://voice-api:8000

Docker Compose

The admin service runs from a separate docker-compose file:

Location: ~/ravenhelm/docs/AI-ML-Platform/norns-agent/admin/docker-compose.service.yml

---

Troubleshooting

Issue: Login Fails

Symptoms: Can't authenticate with Zitadel

Solutions:

1. Verify Zitadel client configuration
2. Check AUTH_SECRET is set in container
3. Clear browser cookies
4. Check Zitadel logs: docker logs zitadel

Issue: Sessions Page Shows "Failed to load"

Symptoms: Sessions page can't fetch data

Solutions:

1. Verify NORNS_API_KEY is set in container:

   docker exec norns-admin env | grep NORNS

2. Check norns-agent is running:

   curl -H "X-API-Key: $NORNS_API_KEY" http://localhost:3901/sessions/stats

3. Check agent logs: docker logs norns-agent

Issue: Document Chunks Not Loading

Symptoms: Document detail modal shows error

Solutions:

1. Verify document exists in database
2. Check norns-agent logs for chunk retrieval errors
3. Verify API key authentication

Issue: Real-time Updates Not Working

Symptoms: Transcript doesn't update in real-time

Solutions:

1. Verify SSE endpoint is accessible
2. Check browser dev tools Network tab for EventSource connection
3. Verify session_id format matches database

---

Related

• Norns Agent - Backend API
• Norns Web Crawling - Web content ingestion
• Norns Telephony - Voice calls integration
• Bifrost - Tool gateway
• Langfuse - LLM observability
• LangGraph - Agent workflow engine
• User Profile System - Profile management & insights