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

> Discover how to access and use the Next.js dashboard for OmniRoute. This guide explains how to get to the dashboard at the API's default port, 20128, once the server is running.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-28

---

**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:

```bash
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:

```bash

# 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:

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```nginx
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/layout.tsx) and [`page.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/page.tsx) defining the core structure.
- Authentication is handled by [`src/server/authz/routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts), applying API-key requirements when `REQUIRE_API_KEY` is enabled.
- Real-time components like [`ProviderStatus.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`.