OmniRoute Claude Code Guide: Launch, Multi-Model Profiles and VPS

1. Install and start OmniRoute

npm install -g omniroute

omniroute

Needs Node.js 22.22.2+ (22.x) or 24–26. The dashboard opens at http://localhost:20128 and the API is at http://localhost:20128/v1.

Optional: skip the native warm-up

OMNIROUTE_SKIP_POSTINSTALL=1 npm install -g omniroute

For CI, headless or slow machines, the README lets you skip the post-install native warm-up (SQLite). The binary copy and repair hook still runs. CI=1 skips it too.

2. Connect a provider

curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_OMNIROUTE_KEY"

In the dashboard, open Providers and add a provider with your own API key or account. That provider's prices, quotas and terms still apply. Then copy an API key from Dashboard → Endpoints.

3. Launch Claude Code through OmniRoute

omniroute launch

omniroute run claude --model openai/gpt-5.4

omniroute launch reads the active context, checks the server is healthy, sets the Anthropic variables and starts claude. omniroute run claude does the same with a model you choose.

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}

Write one profile per model

omniroute setup-claude --dry-run

omniroute setup-claude

omniroute setup-claude --only glm,kimi

setup-claude reads the live /v1/models list and writes ~/.claude/profiles/<name>/settings.json for each model, with names such as glm52, kimi-k27 or deepseek-pro. Each profile is its own CLAUDE_CONFIG_DIR, with separate settings, history and cache. Your API key is never written into a profile.

Launch a profile

omniroute launch --profile kimi-k27

CLAUDE_CONFIG_DIR=~/.claude/profiles/glm52 claude

omniroute launch --profile adds the API key from the active context. Without it, export ANTHROPIC_AUTH_TOKEN yourself and point CLAUDE_CONFIG_DIR at the profile.

Or map Claude Code's tiers to different models

export ANTHROPIC_DEFAULT_OPUS_MODEL="glm/glm-5.2"

export ANTHROPIC_DEFAULT_SONNET_MODEL="kmc/kimi-k2.6"

export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm/glm-4.7-flash"

Instead of one ANTHROPIC_MODEL, send each Claude Code tier to a different OmniRoute model. The model ids below are the docs' examples; use ids from your own /v1/models list.

1. Run the Docker image on the VPS, bound to loopback

docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -e OMNIROUTE_MEMORY_MB=8192 --memory=10g \
  -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest

:latest follows the newest published stable release; pin a version tag such as :3.8.51 if you want repeatable deploys. The image's 1024 MB heap is for the dashboard and light chat; a coding agent like Claude Code needs about an 8192 MB heap in a container with at least 10 GB of memory.

2. Set your own secrets

openssl rand -hex 32

The VM guide puts JWT_SECRET, INITIAL_PASSWORD, API_KEY_SECRET, STORAGE_ENCRYPTION_KEY and the other secrets in an .env file passed with --env-file. Generate each secret separately. Set REQUIRE_API_KEY=true so every /v1/* request needs a valid key (it is false by default and does not cover GET /v1/models).

3. Put HTTPS in front, close everything else

ufw default deny incoming

ufw allow 22/tcp && ufw allow 80/tcp && ufw allow 443/tcp

ufw enable

Keep port 20128 on 127.0.0.1 and let a reverse proxy (the official guide uses nginx with HTTPS) forward to http://127.0.0.1:20128. Allow only SSH, 80 and 443 in the firewall.

4. Connect from your laptop and launch

npm install -g omniroute

omniroute connect https://omni.example.com --scope write

omniroute setup-claude

omniroute launch

omniroute connect trades the management password for a scoped access token (oma_live_…, admin by default; use --scope read or write to limit it) and saves it as the active context in ~/.omniroute/config.json. After that, omniroute launch and setup-claude target the VPS with no extra flags. Access tokens manage the server; inference API keys (sk-…) are separate.

Go back to Claude Code's normal setup

unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL

claude

omniroute launch and profiles only set variables for that session or live in their own CLAUDE_CONFIG_DIR. If you added the env block to settings.json by hand, remove ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN and the other OmniRoute entries, then start a new claude session.

Uninstall OmniRoute (npm)

npm uninstall -g omniroute

rm -rf ~/.omniroute

From the official uninstall guide. Removing ~/.omniroute is optional and permanently deletes your provider connections, API keys and usage history.

Check nothing is left

npm list -g omniroute

ls -la ~/.omniroute/

pgrep -f omniroute

Also from the uninstall guide. If a process is still running, stop it with pkill -f omniroute.