OmniRoute Local Installation and Startup Validation

This page is for first-time HagiCode users who want the shortest OmniRoute setup path: start the local service, verify that http://localhost:20128/v1 works, and confirm that both the Dashboard and API are available.

Recommended path

This first version keeps the most stable path first: npm install -g omniroute, omniroute, Dashboard at http://localhost:20128, and the OpenAI-compatible Base URL at http://localhost:20128/v1. Docker, VPS, and more advanced deployment modes stay in the optional section.

Prerequisites

• Node.js is already installed. Complete Installing Node.js first if needed.
• Local port 20128 is 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:

npm install -g omniroute
omniroute

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:

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

Then request /v1/models:

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

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