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

> Discover the default port for the OmniRoute API and dashboard. OmniRoute uses TCP port 20128 as the default bind address for both. Learn more about this configuration.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/runtime/ports.ts) where the constant `DEFAULT_PORT` is initialized to `20128`:

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

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

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

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