# How to Access the OmniRoute Dashboard: Web UI, CLI, and Configuration

> Learn how to access the OmniRoute dashboard using the web UI or CLI. Explore OmniRoute configuration and management with this quick guide.

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

---

**The OmniRoute dashboard is available at `http://localhost:20128/dashboard` by default, and you can open it directly in your browser or launch it automatically via the `omniroute dashboard` CLI command.**

OmniRoute is an open-source API gateway and routing engine that includes a built-in web dashboard for managing providers, combos, and resilience settings. To access the OmniRoute dashboard, you can either navigate to the local server URL manually or use the dedicated CLI command that detects the correct port configuration. This guide covers all available access methods, port customization options, and the underlying Next.js App Router architecture that serves the interface.

## Default URL to Access the OmniRoute Dashboard

By default, the OmniRoute server starts on **port 20128**, making the dashboard accessible at:

```bash
http://localhost:20128/dashboard

```

When the server initializes, the root URL (`/`) automatically redirects to the dashboard. This behavior is implemented in [[`src/app/page.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/page.tsx)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/page.tsx), ensuring users immediately reach the management interface when visiting the base address.

You can customize the port using either the `PORT` environment variable or the `--port` CLI flag:

```bash

# Using environment variable

PORT=8080 npx omniroute serve

# Using CLI flag

npx omniroute serve --port 8080

```

This flexibility allows you to run OmniRoute on any available port in your environment, whether avoiding conflicts or adhering to specific infrastructure requirements.

## CLI Commands to Access the OmniRoute Dashboard

The **OmniRoute CLI** provides a dedicated command to open the dashboard without manually typing URLs. Running `omniroute dashboard` determines the effective port (respecting the `PORT` environment variable or `--port` flag) and launches your default browser pointing to the correct dashboard URL.

On Windows, the implementation uses `rundll32` to avoid spawning a shell process, as documented in [[`skills/cli-serve/SKILL.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/skills/cli-serve/SKILL.md)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/skills/cli-serve/SKILL.md).

```bash

# Start the server first

npx omniroute serve

# In another terminal, open the dashboard

omniroute dashboard

# If you customized the port, specify it explicitly

omniroute dashboard --port 8080

```

This approach is particularly useful during development workflows, eliminating the need to remember specific port numbers or URL paths.

## Dashboard Navigation and Page Structure

The OmniRoute dashboard is built as a **Next.js App Router** application residing under `src/app/(dashboard)/dashboard/`. The interface is organized into feature-specific pages routed behind the common `/dashboard` prefix:

- **Home page**: `/dashboard` → [`src/app/(dashboard)/home/page.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/(dashboard)/home/page.tsx)
- **Providers list**: `/dashboard/providers` → [`src/app/(dashboard)/dashboard/providers/page.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/(dashboard)/dashboard/providers/page.tsx)
- **Combo manager**: `/dashboard/combos` → [`src/app/(dashboard)/dashboard/combos/page.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/(dashboard)/dashboard/combos/page.tsx)
- **Health and circuit breakers**: `/dashboard/health` → [`src/app/(dashboard)/dashboard/health/page.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/(dashboard)/dashboard/health/page.tsx)
- **Settings** (general, resilience, routing): `/dashboard/settings/<tab>` → [`src/app/(dashboard)/dashboard/settings/page.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/(dashboard)/dashboard/settings/page.tsx)

Each page leverages React Server Components where appropriate, with interactive elements managed through client-side hydration. The settings page includes sub-tabs for granular configuration of feature flags, which are controlled via [`src/app/(dashboard)/dashboard/settings/components/FeatureFlagsGrid.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/app/(dashboard)/dashboard/settings/components/FeatureFlagsGrid.tsx).

## Real-Time Monitoring via WebSocket

OmniRoute supports a live event stream through a **WebSocket connection** at the `/live` endpoint. This stream provides real-time updates about gateway events, health status changes, and traffic metrics directly within the dashboard.

The live WebSocket server starts automatically when the `OMNIROUTE_ENABLE_LIVE_WS` feature flag is set to `true` (the default), as defined in [[`src/shared/constants/featureFlagDefinitions.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/featureFlagDefinitions.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.51/src/shared/constants/featureFlagDefinitions.ts).

```typescript
// Example: subscribing to the live‑WS stream (port 20129 by default)
const ws = new WebSocket(`ws://${location.host}/live`);
ws.onmessage = (ev) => console.log("Dashboard event:", ev.data);

```

By default, the WebSocket server listens on port 20129, though this may vary based on your configuration. You can disable this feature through the dashboard's settings interface if real-time updates are not required for your deployment.

## Programmatic Dashboard Navigation

When extending the dashboard or building custom integrations, you can navigate programmatically using Next.js routing:

```tsx
import { useRouter } from "next/navigation";

export function ProviderButton({ providerId }: { providerId: string }) {
  const router = useRouter();

  const goToProvider = () => {
    router.push(`/dashboard/providers/${encodeURIComponent(providerId)}`);
  };

  return <button onClick={goToProvider}>Open Provider Settings</button>;
}

```

This pattern is consistent across all dashboard segments, utilizing the `/dashboard` base path followed by the specific resource identifier.

## Summary

To access the OmniRoute dashboard effectively, remember these key points:

- The default access URL is `http://localhost:20128/dashboard`, with automatic redirection from the root path via [`src/app/page.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/page.tsx).
- Use the `omniroute dashboard` CLI command to open the interface automatically, which respects custom ports specified via `--port` or the `PORT` environment variable.
- The dashboard is built with Next.js App Router, organizing features under `src/app/(dashboard)/dashboard/` with specific pages for providers, combos, health, and settings.
- Real-time monitoring is available through the `/live` WebSocket endpoint, controlled by the `OMNIROUTE_ENABLE_LIVE_WS` feature flag.

## Frequently Asked Questions

### How do I change the default port to access the OmniRoute dashboard?

You can modify the port using the `PORT` environment variable or the `--port` CLI flag when starting the server. For example, run `PORT=8080 npx omniroute serve` to access the dashboard at `http://localhost:8080/dashboard`. The CLI `omniroute dashboard` command will detect this change automatically or accept an explicit `--port` argument.

### Can I access the OmniRoute dashboard from a remote machine?

Yes, the dashboard binds to the host specified during server startup. By default it listens on localhost, but you can configure it to bind to `0.0.0.0` or a specific network interface. Once configured, access the dashboard using the server's IP address or domain name followed by port 20128 (or your custom port) and the `/dashboard` path.

### What does the `omniroute dashboard` CLI command do internally?

The command determines the effective server port by checking the `PORT` environment variable or any provided `--port` argument. It then constructs the dashboard URL and launches the system's default browser. On Windows, it specifically uses `rundll32` to open the URL without spawning an intermediate shell process, as implemented in the CLI serve skill documentation.

### How do I disable the live WebSocket stream in the dashboard?

Set the `OMNIROUTE_ENABLE_LIVE_WS` environment variable to `false` before starting the server, or toggle the feature off through the Settings page in the dashboard interface. This setting is managed via the feature flag definitions in [`src/shared/constants/featureFlagDefinitions.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/featureFlagDefinitions.ts) and rendered in the UI through [`FeatureFlagsGrid.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/FeatureFlagsGrid.tsx).