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

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:

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

# 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/release/v3.8.51/skills/cli-serve/SKILL.md).

# 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
• Providers list: /dashboard/providers → src/app/(dashboard)/dashboard/providers/page.tsx
• Combo manager: /dashboard/combos → src/app/(dashboard)/dashboard/combos/page.tsx
• Health and circuit breakers: /dashboard/health → src/app/(dashboard)/dashboard/health/page.tsx
• Settings (general, resilience, routing): /dashboard/settings/<tab> → 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.

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/release/v3.8.51/src/shared/constants/featureFlagDefinitions.ts).

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

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.
• 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 and rendered in the UI through FeatureFlagsGrid.tsx.

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