### Quick Start OmniRoute Setup

Source: https://github.com/diegosouzapw/omniroute/blob/main/skills/omniroute-cli/SKILL.md

A quick start guide to initiate the OmniRoute server, run the interactive setup wizard, and verify the system's health.

```bash
# 1. Start server
omniroute

# 2. (First run) interactive setup wizard
omniroute setup

# 3. Verify everything is healthy
omniroute doctor
```

--------------------------------

### Install Dependencies and Run Development Server

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/bg/CLAUDE.md

Install project dependencies and start the development server. The installation process automatically generates the .env file from .env.example.

```bash
npm install                    # Install deps (auto-generates .env from .env.example)
npm run dev                    # Dev server at http://localhost:20128
```

--------------------------------

### Install and Run OmniRoute

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/fa/CLAUDE.md

Install dependencies, start the development server, build for production, and run linters or tests. These commands are essential for setting up and maintaining the project.

```bash
npm install                    # Install deps (auto-generates .env from .env.example)

```

```bash
npm run dev                    # Dev server at http://localhost:20128

```

```bash
npm run build                  # Production build (Next.js 16 standalone)

```

```bash
npm run lint                   # ESLint (0 errors expected; warnings are pre-existing)

```

```bash
npm run typecheck:core         # TypeScript check (should be clean)

```

```bash
npm run typecheck:noimplicit:core  # Strict check (no implicit any)

```

```bash
npm run test:coverage          # Unit tests + coverage gate (60% min)

```

```bash
npm run check                  # lint + test combined

```

```bash
npm run check:cycles           # Detect circular dependencies

```

--------------------------------

### Install OmniRoute from Source

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/guides/SETUP_GUIDE.md

Installs OmniRoute from source and starts the development server. Environment variables can be used to customize ports and base URLs. A .env file is auto-generated on first run and subsequent installs will not overwrite it.

```bash
npm install
PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```

--------------------------------

### Install Dependencies and Run Development Server

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/in/CLAUDE.md

Install project dependencies using npm install. Start the development server with npm run dev. This command also auto-generates the .env file from .env.example.

```bash
npm install          # Install deps (auto-generates .env from .env.example)
npm run dev          # Dev server at http://localhost:20128
```

--------------------------------

### Quick Setup Script

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/phi/docs/reference/CLI-TOOLS.md

A bash script to install and configure various AI CLIs for OmniRoute with a single command.

```APIDOC
## Quick Setup Script (One Command)

```bash
# Install all CLIs and configure for OmniRoute (replace with your key and server URL)
OMNIROUTE_URL="http://localhost:20128/v1"
OMNIROUTE_KEY="sk-your-omniroute-key"

npm install -g @anthropic-ai/claude-code @openai/codex opencode-ai cline kilocode @qwen-code/qwen-code

# Kiro CLI
apt-get install -y unzip 2>/dev/null; curl -fsSL https://cli.kiro.dev/install | bash

# Write configs
mkdir -p ~/.claude ~/.codex ~/.config/opencode ~/.continue

cat > ~/.claude/settings.json   <<< "{\"apiBaseUrl\":\"$OMNIROUTE_URL\",\"apiKey\":\"$OMNIROUTE_KEY\"}"
cat > ~/.codex/config.yaml      <<< "model: auto\napiKey: $OMNIROUTE_KEY\napiBaseUrl: $OMNIROUTE_URL"
cat >> ~/.bashrc << EOF
export OPENAI_BASE_URL="$OMNIROUTE_URL"
export OPENAI_API_KEY="$OMNIROUTE_KEY"
export ANTHROPIC_BASE_URL="$OMNIROUTE_URL"
export ANTHROPIC_API_KEY="$OMNIROUTE_KEY"
EOF

source ~/.bashrc
echo "✅ All CLIs installed and configured for OmniRoute"
```
```

--------------------------------

### Install and Run Desktop Application

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/ro/docs/guides/USER_GUIDE.md

Commands to install dependencies, run the Electron app in development mode, or start it in production.

```bash
# From the electron directory:
cd electron
npm install
```

```bash
# Development mode (connect to running Next.js dev server):
npm run dev
```

```bash
# Production mode (uses standalone build):
npm start
```

--------------------------------

### Setup Environment Variables

Source: https://github.com/diegosouzapw/omniroute/blob/main/CLAUDE.md

Copy the example environment file and generate necessary secrets for JWT and API keys.

```bash
cp .env.example .env
openssl rand -base64 48
openssl rand -hex 32
```

--------------------------------

### Install Dependencies and Run Development Server

Source: https://github.com/diegosouzapw/omniroute/blob/main/CLAUDE.md

Install project dependencies using npm. This command also auto-generates the .env file from .env.example. Use 'npm run dev' to start the development server.

```bash
npm install
npm run dev
```

--------------------------------

### VPS Deployment Steps

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/da/docs/guides/USER_GUIDE.md

Clone the repository, install dependencies, build the project, set environment variables, and start the server for VPS deployment.

```bash
git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute && npm install && npm run build

export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"
export DATA_DIR="/var/lib/omniroute"
export PORT="20128"
export HOSTNAME="0.0.0.0"
export NODE_ENV="production"
export NEXT_PUBLIC_BASE_URL="http://localhost:20128"
export API_KEY_SECRET="endpoint-proxy-api-key-secret"

npm run start
# Or: pm2 start npm --name omniroute -- start
```

--------------------------------

### MCP Server Guide

Source: https://github.com/diegosouzapw/omniroute/blob/main/README.md

A guide to installing and using the MCP Server, including transports and tool references.

```APIDOC
## MCP Server Guide

### Description
This guide provides instructions for MCP installation, details on available transports, and a reference for MCP tools.

### Endpoint
[See docs/MCP-SERVER.md for the full guide]
```

--------------------------------

### Interactive OmniRoute Setup

Source: https://github.com/diegosouzapw/omniroute/blob/main/skills/omniroute-cli-admin/SKILL.md

Initiate a step-by-step interactive setup process for OmniRoute.

```bash
omniroute setup                        # Step-by-step interactive setup
```

--------------------------------

### Install and Manage Fail2ban

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/az/docs/ops/VM_DEPLOYMENT_GUIDE.md

Install fail2ban to protect your SSH service from brute-force attacks. Enable and start the service, and check its status for the SSH daemon.

```bash
apt install -y fail2ban
systemctl enable fail2ban
systemctl start fail2ban

# Check status
fail2ban-client status sshd
```

--------------------------------

### Build and Start OmniRoute for Production

Source: https://github.com/diegosouzapw/omniroute/blob/main/CONTRIBUTING.md

Builds the production-ready application and starts the server. Use for deployment.

```bash
# Production build
npm run build
npm run start
```

--------------------------------

### Install CLI Tools

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/reference/CLI-TOOLS.md

Install various AI-powered CLI tools using npm. Ensure Node.js is up-to-date. Kiro CLI requires additional setup.

```bash
# Claude Code (Anthropic)
npm install -g @anthropic-ai/claude-code

# OpenAI Codex
npm install -g @openai/codex

# OpenCode
npm install -g opencode-ai

# Cline
npm install -g cline

# KiloCode
npm install -g kilocode

# Qwen Code (Alibaba)
npm install -g @qwen-code/qwen-code

# Kiro CLI (Amazon — requires curl + unzip)
apt-get install -y unzip   # on Debian/Ubuntu
curl -fsSL https://cli.kiro.dev/install | bash
export PATH="$HOME/.local/bin:$PATH"   # add to ~/.bashrc
```

--------------------------------

### Install OmniRoute v3.8.0 Globally

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/releases/v3.8.0.md

Use npm to install the latest version of OmniRoute globally. Optionally, re-run the setup to see the new tier tour.

```bash
npm install -g omniroute@3.8.0
omniroute setup   # optional — re-runs onboarding to show new tier tour
```

--------------------------------

### Example Playbook: Maximize Paid Subscription + Cheap Backup

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/az/README.md

This playbook combines premium AI models for high quality with a cost-effective backup option to ensure near-zero interruption.

```txt
Combo: "maximize-claude"
  1. cc/claude-opus-4-7
  2. glm/glm-4.7
  3. if/kimi-k2-thinking

Monthly cost: $20 + small backup spend
Outcome: higher quality, near-zero interruption
```

--------------------------------

### OpenAI Codex (Plus/Pro) Provider Setup

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/cs/README.md

Setup guide for OpenAI Codex, including OAuth, quota management, and policy toggles for 5-hour and weekly limits.

```APIDOC
### OpenAI Codex (Plus/Pro)

```bash
Dashboard → Providers → Connect Codex
→ OAuth login (port 1455)
→ 5-hour + weekly reset

Models:
  cx/gpt-5.2-codex
  cx/gpt-5.1-codex-max
```

#### Codex Account Limit Management (5h + Weekly)

Each Codex account now has policy toggles in `Dashboard -> Providers`:

- `5h` (ON/OFF): enforce the 5-hour window threshold policy.
- `Weekly` (ON/OFF): enforce the weekly window threshold policy.
- Threshold behavior: when an enabled window reaches >=90% usage, that account is skipped.
- Rotation behavior: OmniRoute routes to the next eligible Codex account automatically.
- Reset behavior: when the provider `resetAt` time passes, the account becomes eligible again automatically.

Scenarios:

- `5h ON` + `Weekly ON`: account is skipped when either window reaches threshold.
- `5h OFF` + `Weekly ON`: only weekly usage can block the account.
- `5h ON` + `Weekly OFF`: only 5-hour usage can block the account.
- `resetAt` passed: account re-enters rotation automatically (no manual re-enable).
```

--------------------------------

### Install OmniRoute Application

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/guides/SETUP_GUIDE.md

Installs the OmniRoute application by copying necessary files and creating a startup script. It ensures directories exist and sets up the executable.

```sh
vmkdir usr/lib/omniroute/.next
vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

for _d in \
	.next/standalone/.next/server/app/dashboard \
	.next/standalone/.next/server/app/dashboard/settings \
	.next/standalone/.next/server/app/dashboard/providers; do
	touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
done

cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
vbin "${WRKDIR}/omniroute"
```

--------------------------------

### Install and Run Electron Desktop App

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/bn/docs/guides/USER_GUIDE.md

Commands to install dependencies, run the app in development mode, and start the production build for the Omniroute Electron desktop application.

```bash
# From the electron directory:
cd electron
npm install

# Development mode (connect to running Next.js dev server):
npm run dev

# Production mode (uses standalone build):
npm start
```

--------------------------------

### OmniRoute Setup and Initialization

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/reference/CLI-TOOLS.md

Commands for setting up OmniRoute, either interactively or in a non-interactive mode for CI/automation. Allows direct password setting and adding/testing providers.

```bash
omniroute setup                        # Interactive setup wizard
omniroute setup --non-interactive      # CI/automation mode (reads env vars + flags)
omniroute setup --password '<value>'   # Set admin password directly
omniroute setup --add-provider \
  --provider openai \
  --api-key '<value>' \
  --test-provider                      # Add and test a provider in one shot
```

--------------------------------

### Electron App Installation and Development

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/guides/USER_GUIDE.md

Commands to install dependencies, run the Electron app in development mode connected to a Next.js dev server, or start it in production mode.

```bash
cd electron
npm install
```

```bash
# Development mode (connect to running Next.js dev server):
npm run dev
```

```bash
# Production mode (uses standalone build):
npm start
```

--------------------------------

### Install OmniRoute on Arch Linux (AUR)

Source: https://github.com/diegosouzapw/omniroute/blob/main/README.md

Install OmniRoute on Arch Linux using the AUR helper 'yay'. This command also enables and starts the OmniRoute systemd service.

```bash
yay -S omniroute-bin && systemctl --user enable --now omniroute.service
```

--------------------------------

### Run OmniRoute from Source

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/az/README.md

Set up environment variables, install dependencies, and run the development server for OmniRoute when running from source.

```bash
cp .env.example .env
npm install
PORT=20128 DASHBOARD_PORT=20129 NEXT_PUBLIC_BASE_URL=http://localhost:20129 npm run dev
```

--------------------------------

### Install and Enable Fail2ban

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/cs/docs/ops/VM_DEPLOYMENT_GUIDE.md

Install fail2ban to protect SSH from brute-force attacks by monitoring log files and banning IPs that show malicious activity. Ensure the service is enabled and started.

```bash
apt install -y fail2ban
systemctl enable fail2ban
systemctl start fail2ban
```

```bash
fail2ban-client status sshd
```

--------------------------------

### Install OmniRoute Application

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/bg/docs/guides/USER_GUIDE.md

Installs the OmniRoute application by copying the built files and creating a startup script. It ensures necessary directories are created and configures environment variables for runtime.

```sh
vmkdir usr/lib/omniroute/.next
vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

# Prevent removal of empty Next.js app router dirs by the post-install hook
for _d in \
	.next/standalone/.next/server/app/dashboard \
	.next/standalone/.next/server/app/dashboard/settings \
	.next/standalone/.next/server/app/dashboard/providers; do
	touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
done

cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
vbin "${WRKDIR}/omniroute"
```

--------------------------------

### A2A Setup

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/fi/README.md

Guide for discovering agents, sending tasks, and managing the lifecycle of Agent-to-Agent communication.

```APIDOC
## A2A Setup (Agent2Agent)

### Description
Discover agents, send tasks, and manage the A2A communication lifecycle.

### Discover Agent
```bash
curl http://localhost:20128/.well-known/agent.json
```

### Send Task
```bash
curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}'
```

### Manage Lifecycle
- `GET /api/a2a/status`
- `GET /api/a2a/tasks`
- `GET /api/a2a/tasks/:id`
- `POST /api/a2a/tasks/:id/cancel`

### Operational UI
Access `/dashboard/a2a` for task/state/stream observability and smoke actions.
```

--------------------------------

### Cloud Sync Configuration Example

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/guides/TROUBLESHOOTING.md

Example environment variables for configuring OmniRoute cloud sync. Ensure BASE_URL and CLOUD_URL are correctly set.

```text
BASE_URL=http://localhost:20128
CLOUD_URL=https://omniroute.dev
```

--------------------------------

### A2A Setup (Agent2Agent)

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/in/README.md

Guide for discovering agents, sending tasks, and managing the lifecycle of Agent2Agent communication.

```APIDOC
## A2A Setup (Agent2Agent)

### Description
Discover agents, send tasks, and manage the Agent2Agent communication lifecycle.

### Discover Agent
```bash
curl http://localhost:20128/.well-known/agent.json
```

### Send Task
```bash
curl -X POST http://localhost:20128/a2a \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"setup-a2a","method":"message/send","params":{"skill":"quota-management","messages":[{"role":"user","content":"Summarize quota status."}]}}'
```

### Manage Lifecycle
- `GET /api/a2a/status`
- `GET /api/a2a/tasks`
- `GET /api/a2a/tasks/:id`
- `POST /api/a2a/tasks/:id/cancel`

### Operational UI
Access `/dashboard/a2a` for task/state/stream observability and smoke actions.
```

--------------------------------

### Install OmniRoute Application

Source: https://github.com/diegosouzapw/omniroute/blob/main/docs/i18n/az/docs/guides/USER_GUIDE.md

Installs the OmniRoute application by copying the standalone bundle and creating a startup script. It also ensures specific directories are preserved.

```sh
do_install() {
	vmkdir usr/lib/omniroute/.next
	vcopy .next/standalone/. usr/lib/omniroute/.next/standalone

	# Prevent removal of empty Next.js app router dirs by the post-install hook
	for _d in \
		.next/standalone/.next/server/app/dashboard \
		.next/standalone/.next/server/app/dashboard/settings \
		.next/standalone/.next/server/app/dashboard/providers; do
		touch "${DESTDIR}/usr/lib/omniroute/${_d}/.keep"
	done

	cat > "${WRKDIR}/omniroute" <<'EOF'
#!/bin/sh
export PORT="${PORT:-20128}"
export DATA_DIR="${DATA_DIR:-${XDG_DATA_HOME:-${HOME}/.local/share}/omniroute}"
export APP_LOG_TO_FILE="${APP_LOG_TO_FILE:-false}"
mkdir -p "${DATA_DIR}"
exec node /usr/lib/omniroute/.next/standalone/server.js "$@"
EOF
	vbin "${WRKDIR}/omniroute"
}

post_install() {
	vlicense LICENSE
}

```