What Is the Default Port for the OmniRoute API and Dashboard?

OmniRoute uses TCP port 20128 as the default bind address for both its HTTP API and the administrative dashboard, defined as the DEFAULT_PORT constant in the runtime ports module.

OmniRoute is an open-source routing platform that exposes a programmatic HTTP API and a built-in web dashboard for monitoring routes and configurations. When you start the server without custom environment variables, both interfaces share the same default port. This article examines how port 20128 is hard-coded, how the runtime resolution logic selects the actual listening port, and how to override these defaults safely.

Where the Default Port Is Hard-Coded

The canonical default port is defined in src/lib/runtime/ports.ts where the constant DEFAULT_PORT is initialized to 20128:

// src/lib/runtime/ports.ts
export const DEFAULT_PORT = 20128;

This single constant serves as the ultimate fallback for both the API listener and the dashboard UI. According to the OmniRoute source code, the resolution logic lives in the same file and is validated by unit tests in tests/unit/zed-hosted-loopback-port-derivation.test.ts, which assert that the system correctly falls back to 20128 when no environment overrides are present.

How Runtime Port Resolution Works

OmniRoute does not bind to 20128 unconditionally. The runtime ports module implements a hierarchical resolution strategy that checks environment variables in a specific order before falling back to the default.

The Resolution Hierarchy

When OmniRoute initializes, the internal resolveDashboardLoopbackPort logic (and the associated getRuntimePorts utility) evaluates the following precedence:

1. OMNIROUTE_PORT – An explicit override that sets the same port for both the API and dashboard.
2. PORT – A generic fallback variable used by many hosting platforms; applies to both services if OMNIROUTE_PORT is unset.
3. DASHBOARD_PORT – A specific override used only for the dashboard when you need the UI to listen on a different interface than the API.
4. DEFAULT_PORT (20128) – The hard-coded constant used when none of the above variables are defined.

Accessing Resolved Ports Programmatically

You can inspect the final resolved ports at runtime using the getRuntimePorts function exported from the runtime module:

import { getRuntimePorts } from '@/lib/runtime/ports';

const { apiPort, dashboardPort } = getRuntimePorts();

console.log(`API bound to: ${apiPort}`);        // → 20128 (or override)
console.log(`Dashboard bound to: ${dashboardPort}`); // → 20128 (or override)

This function aggregates the environment checks and returns the actual ports that the HTTP server and dashboard WebSocket will bind to.

Overriding the Default Port

To change the default port 20128, set one of the supported environment variables before starting the process.

Use OMNIROUTE_PORT to unify both services on a custom port:

OMNIROUTE_PORT=3000 npm run dev

# API and dashboard both available at http://localhost:3000

To split the API and dashboard onto separate ports, combine PORT and DASHBOARD_PORT:

PORT=3000 DASHBOARD_PORT=3001 npm start

# API → http://localhost:3000

# Dashboard → http://localhost:3001

These variables are documented in the repository's .env.example file, which demonstrates the recommended configuration pattern for containerized and bare-metal deployments.

Summary

• Default value: OmniRoute defaults to port 20128 for both API and dashboard traffic.
• Source location: The constant is defined as DEFAULT_PORT = 20128 in src/lib/runtime/ports.ts.
• Override options: Use OMNIROUTE_PORT for unified binding, or PORT/DASHBOARD_PORT for split configurations.
• Runtime inspection: Import getRuntimePorts from the runtime module to verify which ports are active.
• Validation: The resolution logic is covered by tests/unit/zed-hosted-loopback-port-derivation.test.ts.

Frequently Asked Questions

Can the API and dashboard run on different ports?

Yes. While they default to sharing port 20128, you can assign distinct ports by setting PORT for the API and DASHBOARD_PORT for the dashboard. If both variables are present, OmniRoute binds each service to its respective port instead of the unified default.

What happens if port 20128 is already in use?

OmniRoute will throw a runtime EADDRINUSE error and exit if it cannot bind to the resolved port. To avoid this, either free the port or override the default using OMNIROUTE_PORT or PORT before starting the server.

How do I verify which port OmniRoute is actually using?

Import the getRuntimePorts function from src/lib/runtime/ports and call it after initialization. It returns an object containing apiPort and dashboardPort, reflecting the final resolution of environment variables and the 20128 fallback.

Is the default port configurable in a settings file?

No permanent configuration file changes the default. OmniRoute exclusively uses environment variables for port configuration at runtime. The .env.example file in the repository root provides a template for setting these variables in your deployment environment.

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