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

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, 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, 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:

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:

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:

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:

omniroute contexts list

Switch to a specific context:

omniroute contexts use 192.168.0.15

Return to local management:

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:

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:

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:

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:

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:

#!/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.
• 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}