How to Access and Use the Next.js Dashboard for OmniRoute: Complete Guide

The Next.js dashboard for OmniRoute runs on the same port as the API (default 20128) and is accessible at the root URL without any additional path segment once the server is running.

OmniRoute ships with a built-in Next.js dashboard that provides a real-time web interface for monitoring LLM providers, routing strategies, and system metrics. This React-based UI is served by the same Next.js application that handles API requests, enabling seamless integration of management capabilities with the core routing engine.

What Is the OmniRoute Next.js Dashboard?

The OmniRoute Next.js dashboard is a full-screen React UI built with the Next.js App Router architecture. Unlike external monitoring tools, this dashboard compiles directly into the OmniRoute server and shares the same HTTP listener as the API endpoints.

The dashboard provides comprehensive visibility into the routing layer:

• Provider Overview: Displays all configured LLM providers, health status, circuit-breaker states, and per-credential cooldowns.
• Combo Routing UI: Visualizes the active combo-routing strategy, target selection algorithms, and real-time request distribution across models.
• Request Log & Metrics: Streams live Server-Sent Events (SSE) showing incoming requests, responses, latency measurements, token usage, and error rates.
• Service Management: Controls embedded services such as Qdrant and Ollama, including start/stop functionality and log viewing.
• Authentication Integration: Respects the REQUIRE_API_KEY environment variable, applying the same API-key protection to UI routes as API routes.
• Localization & Theming: Supports NEXT_PUBLIC_LOCALE settings and theme configuration defined in the environment.

How to Access the Dashboard

Default Local Development Access

When you start the OmniRoute server, the dashboard automatically becomes available at the root URL of the configured port.

Start the server using the development command:

npm run dev

Then open your browser to the default address:

http://localhost:20128

The dashboard renders immediately at the root path (/) without requiring additional URL segments.

Production and Custom Port Configuration

If you override the default port using the PORT environment variable, access the dashboard at your custom host and port combination:

# Start with custom port

PORT=8080 npm run start

# Access dashboard

http://localhost:8080

Authenticated Access

When REQUIRE_API_KEY is enabled, the dashboard inherits the same authentication middleware as API routes. You can access the protected dashboard by including the API key in the request header:

curl -H "x-api-key: YOUR_API_KEY" http://localhost:20128

For browser access, the dashboard uses the same authentication mechanism defined in src/server/authz/routeGuard.ts, which classifies dashboard routes as either local-only or API-key-protected based on your configuration.

Dashboard Architecture and Key Source Files

OmniRoute organizes the dashboard code within the Next.js App Router convention, grouping route-specific files under the (dashboard) segment to isolate layout and page logic.

Route Structure and Layout

The dashboard entry point resides in the App Router directory structure:

• src/app/(dashboard)/layout.tsx: Implements the root layout component that wraps all dashboard pages, injecting global UI state and shared providers required by the interface.
• src/app/(dashboard)/page.tsx: Renders the main landing page displaying the provider overview, routing status indicators, and live log streams.

These files leverage Next.js server components where possible, hydrating interactive elements on the client side for real-time data updates.

UI Components

Individual dashboard widgets are modularized for maintainability:

• src/app/(dashboard)/components/ProviderStatus.tsx: Renders individual provider health cards, showing circuit-breaker states, latency histograms, and credential validity indicators.

This component architecture allows the dashboard to update specific sections without full page reloads, utilizing React's concurrent features for smooth metric visualization.

Security and Middleware

The dashboard integrates with OmniRoute's unified security layer:

• src/server/authz/routeGuard.ts: Contains the middleware logic that intercepts incoming dashboard requests, classifying them as public, local-only, or API-key-protected based on environment configuration and request origin.
• src/shared/utils/dashboardCsrf.ts: Generates and validates Cross-Site Request Forgery tokens for dashboard form submissions, ensuring that provider management actions require valid session tokens.

Because the dashboard shares the Next.js application instance, all route-level middleware—including CORS headers, Zod schema validation, and authentication checks—applies automatically to UI routes.

Build System

For production deployments, the dashboard bundle is prepared through:

• scripts/build/dashboardEmbed.mjs: A build-time Node.js script that creates the embeddable dashboard bundle, optimizing assets for static serving while preserving dynamic API integration capabilities.

Deploying the Dashboard Behind a Reverse Proxy

When deploying OmniRoute behind Nginx or similar reverse proxies, forward the root path to preserve dashboard functionality:

location / {
    proxy_pass http://127.0.0.1:20128;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    # Preserve authentication headers required by routeGuard.ts

    proxy_set_header X-API-Key $http_x_api_key;
    proxy_set_header Cookie $http_cookie;
}

This configuration ensures that the dashboard receives necessary headers for authentication and CSRF validation while serving the UI at your preferred domain.

Summary

• The Next.js dashboard for OmniRoute runs on the same server instance as the API, typically accessible at http://localhost:20128.
• Dashboard files reside in src/app/(dashboard)/, with layout.tsx and page.tsx defining the core structure.
• Authentication is handled by src/server/authz/routeGuard.ts, applying API-key requirements when REQUIRE_API_KEY is enabled.
• Real-time components like ProviderStatus.tsx visualize provider health and routing metrics without external dependencies.
• The dashboard respects all middleware layers, including CORS, Zod validation, and CSRF protection via dashboardCsrf.ts.

Frequently Asked Questions

What port does the OmniRoute Next.js dashboard run on?

By default, the dashboard runs on port 20128, sharing the same HTTP listener as the API. You can customize this by setting the PORT environment variable before starting the server. The dashboard remains accessible at the root URL regardless of the port configuration.

Is the Next.js dashboard protected by API key authentication?

Yes, when the REQUIRE_API_KEY environment variable is enabled, the dashboard inherits the same protection as API routes. The middleware in src/server/authz/routeGuard.ts intercepts dashboard requests and validates the x-api-key header or query parameter, returning 401 Unauthorized for unauthenticated requests.

Can I customize the OmniRoute dashboard UI?

You can customize the dashboard by modifying the React components in src/app/(dashboard)/ and the utility functions in src/shared/utils/. The build script scripts/build/dashboardEmbed.mjs compiles your changes into the production bundle. Environment variables like NEXT_PUBLIC_LOCALE allow runtime configuration of localization without code changes.

How do I access the dashboard in production deployments?

In production, access the dashboard by navigating to the root URL of your deployed OmniRoute instance (e.g., https://api.yourdomain.com). If running behind a reverse proxy, ensure the proxy forwards headers required for authentication and CSRF validation. The dashboard is always served at the application root, not a subpath like /dashboard.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}