🎛️ Admin Panel User Guide

Complete guide to managing your AgentRegistry registry through the web-based admin dashboard.

Overview

The AgentRegistry Admin Panel is a real-time, WebSocket-powered dashboard that provides complete control over your local NPM registry. It features a modern glassmorphic design with dark mode aesthetics and full responsiveness.

🔐 Security Note

All admin operations are authenticated via session tokens, automatically injected by the server. The panel uses WebSocket for real-time communication and automatic reconnection.

📸 Screenshots

Dashboard Tab Packages Tab Graph Tab Security Tab Logs Tab

Accessing the Panel

Open your browser and navigate to:

http://localhost:4873/-/admin

The panel will automatically connect and display live server statistics.

📊 Dashboard Tab

The main overview of your registry's health and status.

Stats Cards

Metric Description
Packages Total number of packages in your registry
Tarballs Total package versions (tarballs) stored
Quarantine Packages pending security review
Memory Current server memory usage
Scans Total security scans performed
Requests Total HTTP requests handled

Connection Status

The status indicator in the header shows:

  • ● Connected - WebSocket active
  • ● Disconnected - Attempting reconnection

📦 Packages Tab

View and manage all cached packages in your registry.

Features

  • Smart Search - Type in the search box to find packages (local packages prioritized)
  • Sortable List - Click column headers to sort ascending/descending
  • Delete Package - Remove a package and all its versions from cache

💡 Tip

Deleting a cached upstream package will cause it to be re-fetched and re-scanned on the next install request.

🔒 Quarantine Tab

Manage packages blocked by security scanning. All upstream packages pass through quarantine before caching.

Auto-Allow Local Publish

⚡ Agent Workflow Optimization

Toggle at the top of the Quarantine tab controls whether locally published packages bypass quarantine and security scanning. Default: Enabled

  • Enabled: Packages published via npm publish to your local registry skip quarantine for faster agent workflows
  • Disabled: All packages (local + upstream) go through security scanning

Actions

Button Action
✅ Approve Move package to tarballs, making it installable
🗑️ Delete Permanently remove the quarantined file
🔍 View Issues See the security issues that blocked the package

Bulk Actions

  • Approve All - Move all quarantined packages to tarballs (bypassing scan)
  • Rescan All - Re-run security scan; auto-approves packages that now pass
  • Clear All - Delete all quarantined packages

⚠️ Warning

Approving a quarantined package bypasses security checks. Only approve packages you trust completely.

🕸️ Graph Tab

Interactive D3.js force-directed dependency graph visualization.

Navigation

  • Pan - Click and drag the background
  • Zoom - Mouse wheel or pinch gesture
  • Expand Node - Click a package to load its dependencies

Legend

Color Meaning
● Purple Local packages (published to your registry)
● Cyan Upstream packages (from npmjs.org)

Filters

Toggle "Only Local" checkbox to show only your locally published packages and their direct dependencies.

🛡️ Security Tab (IP Allowlist)

Configure IP-based access control for your registry.

Configuration Options

Setting Description
Enable Allowlist Master switch for IP filtering
Mode allow - only listed IPs can access
deny - listed IPs are blocked

Adding IP Rules

Supported pattern formats:

  • 192.168.1.100 - Exact IP match
  • 192.168.1.* - Wildcard (matches 192.168.1.0-255)
  • 10.0.0.0/24 - CIDR notation (10.0.0.0-10.0.0.255)
  • ::1 - IPv6 localhost

Testing Access

Use the "Test IP" feature to verify if a specific IP would be allowed or denied based on current rules.

📜 Audit Tab

Security event log with full audit trail.

Sortable Columns

  • Action - Type of security event
  • Target - Affected package or resource
  • Severity - info, warn, or critical
  • Time - When the event occurred

Export Options

Export audit logs as JSON or CSV for external analysis. Use date filters to narrow the export range.

🔍 Scans Tab

History of all security scans performed on packages.

Scan Details

Column Description
Package Package name scanned
Version Scanned version
Status ✅ Safe or 🚨 Blocked
Issues Number of security issues found
Time Scan duration in milliseconds

Click View on any row to see detailed security findings including severity, description, and affected files.

📡 Requests Tab

HTTP request log for debugging and monitoring.

Logged Information

  • Method - GET, PUT, DELETE, etc.
  • Path - Requested URL path
  • Status - HTTP response code (color-coded)
  • Duration - Response time in milliseconds
  • Time - Request timestamp

💡 Tip

Request logs older than 7 days are automatically cleaned up. Security-related events are preserved in the Audit tab.

📈 Metrics Tab

Real-time server performance metrics.

Available Metrics

Metric Description
RPS Requests per second (current)
Latency Average response time
Cache Hit Rate Percentage of requests served from cache
Memory Usage Current heap utilization

Metrics auto-refresh while the tab is active.