# How to Configure OmniRoute Remote Mode for VPS Management from a Local CLI

> Configure OmniRoute remote mode to manage your VPS from your local CLI. Use scoped access tokens for secure authentication without extra binary installation.

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

---

**OmniRoute remote mode lets you manage a VPS-hosted instance from your local machine using the standard CLI, authenticating via scoped access tokens stored in local contexts without installing a separate binary.**

OmniRoute supports a "remote mode" that allows you to run the server on a VPS, home server, or Tailnet node while driving it from your laptop using the regular `omniroute` CLI. This configuration eliminates the need to install a second binary on your local machine; instead, the CLI communicates with the remote server over HTTP(S) and authenticates each request using scoped access tokens stored in local context files.

## How OmniRoute Remote Mode Works

Remote mode relies on three core components working together: **CLI Contexts**, **Access Tokens**, and the **Management API**.

A **CLI Context** is a saved entry in `~/.omniroute/config.json` that stores the remote server's base URL, access token, and scope. When you run management commands, the CLI reads the active context to determine which server to target.

**Access Tokens** are `oma_live_…` strings minted by the server via password authentication or the dashboard. According to the OmniRoute source code in [`src/app/api/v1/cli/connect/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/cli/connect/route.ts), these tokens are hashed on the server for storage, with the plain token displayed only once during creation. Each token carries a specific **scope**—`read`, `write`, or `admin`—that determines which Management API routes it can access.

The **Management API** exposes routes under `/api/cli/*` (such as `POST /api/cli/connect`, `GET /api/cli/whoami`, and `POST /api/cli/tokens`). As implemented in [`src/lib/authz/tokenValidator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/authz/tokenValidator.ts), each request undergoes scope validation based on the HTTP method and endpoint. For example, token creation and provider configuration require `admin` scope, while listing models only requires `read`.

**Security Boundaries**: Routes that spawn processes—including `/api/services/*` and `/api/mcp/*`—are restricted to loopback-only access. Even tokens with `admin` scope cannot invoke these endpoints remotely, ensuring that process-spawning operations remain confined to the machine running OmniRoute.

## Initial Configuration: Connecting to Your VPS

To begin managing a remote OmniRoute instance, install the CLI locally and establish a connection:

1. Install the CLI globally:

```bash
npm install -g omniroute

```

2. Connect to your VPS using the `connect` command. This sends a POST request to `/api/cli/connect` on the remote server:

```bash
omniroute connect 192.168.0.15

```

The server validates your password and returns a scoped token. The CLI automatically creates a new context named after the host (e.g., "192.168.0.15") and activates it.

3. Verify the active connection:

```bash
omniroute contexts current

```

This displays the base URL (e.g., `http://192.168.0.15:20128`) and token scope (e.g., `admin`).

## Managing Multiple Servers with Contexts

The contexts system allows you to switch between multiple remote servers and your local instance without re-authenticating.

List all saved contexts:

```bash
omniroute contexts list

```

Switch to a specific context:

```bash
omniroute contexts use 192.168.0.15

```

Return to local management:

```bash
omniroute contexts use default

```

The context data persists in `~/.omniroute/config.json`, managed internally by the context manager referenced in the source tree.

## Working with Scoped Tokens

Scoped tokens provide fine-grained access control. The three available scopes are:

- **read**: List resources and view configuration
- **write**: Apply configuration changes and modify settings
- **admin**: Manage providers, policies, OAuth credentials, and create or revoke tokens

Create a read-only token for automation scripts:

```bash
omniroute tokens create --name "ci-runner" --scope read

```

The server generates the token and displays it once. Store this securely in your CI environment.

For one-off commands without saving a context, pass the token directly:

```bash
omniroute models list --remote http://192.168.0.15:20128 --api-key oma_live_abc123

```

## Configuring Downstream CLI Tools

OmniRoute can generate configuration files for compatible AI coding tools using the remote server's model catalog. The `omniroute configure` command and its variants (implemented in `src/lib/cli-helper/config-generator/*`) read the active server's models and write provider-specific configurations.

Configure Codex to use your remote OmniRoute:

```bash
omniroute setup-codex

```

This writes the appropriate configuration to `~/.codex/<model>.config.toml`, pointing Codex at your VPS instance.

For OpenCode with explicit remote parameters:

```bash
omniroute setup-opencode --remote http://192.168.0.15:20128 --api-key oma_live_abc123

```

## CI/CD and Non-Interactive Scripts

For automation pipelines where interactive context switching is impractical, export the token and use the `--remote` flag:

```bash
#!/usr/bin/env bash

# Pre-created read-only token from the OmniRoute dashboard

TOKEN="oma_live_XXXXXXXXXXXXXXXX"
export OMNIROUTE_API_KEY="${TOKEN}"

# Execute commands against the remote server

omniroute models list --remote https://omni.example.com

```

This approach bypasses the context system entirely, relying on environment variables for authentication.

## Summary

- OmniRoute remote mode uses **CLI Contexts** stored in `~/.omniroute/config.json` to manage connections to VPS instances without local server installation.
- Authentication occurs via **scoped access tokens** (`oma_live_…`) minted through `POST /api/cli/connect` and validated by [`src/lib/authz/tokenValidator.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/authz/tokenValidator.ts).
- Three token scopes—**read**, **write**, and **admin**—control access to Management API routes under `/api/cli/*`.
- Process-spawning routes (`/api/services/*`, `/api/mcp/*`) remain **loopback-only** for security, preventing remote execution.
- Use `omniroute contexts` commands to switch between servers, or pass `--remote` and `--api-key` flags for non-interactive usage.
- Always use **HTTPS or Tailnet tunnels** for transport encryption and treat tokens as sensitive secrets.

## Frequently Asked Questions

### What file stores the remote connection settings locally?

OmniRoute saves remote connection settings in `~/.omniroute/config.json`. This file contains **CLI Contexts**—JSON objects that store the remote server's base URL, access token, and scope. The context manager implementation handles reading and writing this file, allowing you to maintain multiple server configurations and switch between them using `omniroute contexts use`.

### Can I use remote mode to start services or MCP servers on the VPS?

No. Routes under `/api/services/*` and `/api/mcp/*` that spawn processes are restricted to **loopback-only** access as a security measure. Even tokens with `admin` scope cannot invoke these endpoints remotely. To manage services or MCP servers, you must execute commands directly on the VPS machine or use SSH to access the local CLI there.

### How do I switch between managing my local OmniRoute and a remote VPS?

Use the `omniroute contexts` command family. Run `omniroute contexts list` to see available connections, then `omniroute contexts use <name>` to activate a specific remote server. To return to local management, execute `omniroute contexts use default`. Each context maintains its own token and server URL, eliminating the need to re-authenticate when switching targets.

### Is it safe to store OmniRoute access tokens in environment variables for CI pipelines?

Storing tokens in environment variables is a common practice for CI/CD, provided you follow security best practices. Create tokens with the **narrowest necessary scope** (typically `read` for deployment scripts) using `omniroute tokens create --scope read`. Ensure your CI platform encrypts environment variables, rotate tokens regularly, and revoke unused tokens via the dashboard or `DELETE /api/cli/tokens/{id}`. Never commit plain tokens to version control.