Skip to content
Hagicode Docs
Blog

OmniRoute Local Installation and Startup Validation

Edit page

The official Desktop app is now the recommended path: download the Windows, macOS, or Linux installer from OmniRoute GitHub Releases. The npm procedure below remains available for headless environments.

This page describes the recommended local OmniRoute path: run npm install -g omniroute, then omniroute start; the Dashboard is at http://localhost:20128 and the OpenAI-compatible Base URL is http://localhost:20128/v1.

Recommended path

Use the recommended local path: npm install -g omniroute, then omniroute start. The Dashboard is at http://localhost:20128, and the OpenAI-compatible Base URL is http://localhost:20128/v1.

Prerequisites

  • Node.js must be >=22.0.0 <23 or >=24.0.0 <27. Node.js 21 and 23 are unsupported. Complete Installing Node.js first if needed.
  • Local ports 20128 and 20129 are available and not already occupied.
  • You have at least one upstream model provider account that you plan to route through OmniRoute.
  • Before integrating HagiCode, a CLI, or an SDK, keep these two addresses separate:
    • Dashboard: http://localhost:20128
    • OpenAI-compatible Base URL: http://localhost: 20128/v1

Install and run locally

Start with the recommended global npm path:

Terminal window
npm install -g omniroute
omniroute start

After the service starts, validate it in this order:

  1. Open http://localhost:20128 in a browser and confirm that the Dashboard loads.
  2. Go to the Endpoints page in the Dashboard and create or copy an API key.
  3. Note the Base URL you will hand to tools later: http://localhost:20128/v1.

Why start with the Dashboard

For the first setup, the Dashboard is the fastest way to confirm that OmniRoute is running, your providers are connected, and an API key exists. If a later client call fails, checking the Dashboard first is usually faster than debugging SDK code immediately.

Validate the running service

Validation 1: confirm the model catalog is readable

Put the key from the Endpoints page into an environment variable:

Terminal window
export OMNIROUTE_API_KEY="replace-with-the-key-you-copied-from-the-Endpoints-page"

Then request /v1/models:

Terminal window
curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}"

If you get a model list back, the OpenAI-compatible endpoint and auth flow are working.

Validation 2: send a minimal chat request

Terminal window
curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "replace-with-a-model-id-from-v1-models",
    "messages": [
      { "role": "user", "content": "Reply with ok." }
    ]
  }'

The goal here is not prompt quality. It is to prove that your chosen model can already be routed through OmniRoute successfully.

Next steps

Installing Node.js
AI Agent CLI Installation
OmniRoute Upstream Project