How to Set Up OmniRoute Remote Mode for Local CLI on VPS

You can manage a VPS-hosted OmniRoute instance from your local machine by installing the CLI, running omniroute connect <host> to mint a scoped access token, and using the saved context to route all subsequent commands to the remote server over HTTPS.

The diegosouzapw/OmniRoute project supports a remote mode that lets you run the server on any host—whether a cloud VPS, home server, or Tailnet node—while controlling it entirely from your laptop using the standard omniroute CLI. This setup 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 a scoped access token. When you set up OmniRoute remote mode for local CLI on VPS, you create a secure, stateful context on your workstation that stores the server's base URL and credentials in ~/.omniroute/config.json.

Architecture of OmniRoute Remote Mode

Remote mode relies on three core components working together: local contexts, server-minted access tokens, and the Management API.

The Context System

A context is a saved entry in ~/.omniroute/config.json that stores the remote server’s base URL, the access token, and its associated scope. According to the source code, the context manager (referenced in src/lib/context-manager.ts) handles persistence, allowing the CLI to remember multiple remote endpoints. When active, the CLI automatically includes the stored token in an Authorization: Bearer … header for every request, ensuring seamless authentication without manual intervention.

Access Tokens and Scope Enforcement

Access tokens are unique strings prefixed with oma_live_ that the server generates via POST /api/cli/connect (implemented in src/app/api/v1/cli/connect/route.ts). The server hashes these tokens for storage and displays the plain text only once. The src/lib/authz/tokenValidator.ts module verifies each incoming request by validating the bearer token against its hash and attaching scope metadata to the request context.

OmniRoute enforces three distinct authorization levels:

• read: Allows listing resources and viewing configuration.
• write: Permits applying configuration changes and deploying updates.
• admin: Grants full access to provider management, OAuth credentials, and token lifecycle operations.

Management API Endpoints

The remote-mode protocol is exposed under /api/cli/*. Key routes include:

• POST /api/cli/connect: Authenticates via password and issues a new scoped token.
• GET /api/cli/whoami: Returns the token’s identity and scope (defined in src/app/api/v1/cli/whoami/route.ts).
• /api/cli/tokens/*: Provides CRUD operations for token management.

Step-by-Step Configuration

Install the CLI Locally

Install the omniroute package globally on your workstation. You only need this single binary to control both local and remote instances.

npm install -g omniroute

Establish the Remote Connection

Run the connect command with your VPS IP address or domain. The CLI will prompt for the server password and automatically negotiate a scoped token.

omniroute connect 192.168.0.15

This command POSTs to /api/cli/connect, receives the token (e.g., oma_live_abc123), and creates a new context named after the host. The context becomes active immediately, directing all future commands to the VPS.

Verify Your Active Context

Confirm that the CLI is targeting the remote server and check your authorization level.

omniroute contexts current

The output displays the base URL (e.g., http://192.168.0.15:20128) and the token scope (e.g., admin). You can also verify token validity by calling the whoami endpoint:

omniroute whoami

Working with Multiple Remote Servers

The omniroute contexts command group lets you manage several environments from a single shell session.

• List all contexts: omniroute contexts list
• Switch contexts: omniroute contexts use <context-name>
• Return to local: omniroute contexts use default

This flexibility allows you to pivot between a production VPS, a staging server, and your local development instance without re-authenticating.

Security Best Practices and Limitations

Token Scope Hierarchy

For operational safety, mint tokens with the minimum necessary scope. Use read tokens for monitoring scripts, write for deployment automation, and reserve admin for manual provider configuration. Create narrow-scoped tokens via the CLI:

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

The server stores only the token hash, so capture the plain oma_live_… string immediately for use in CI secrets.

Network Encryption

Always transport tokens over HTTPS or a private tunnel such as Tailscale. The plaintext token grants direct API access, and compromising it could allow unauthorized configuration changes.

Loopback-Only Restrictions

Certain routes, specifically /api/services/* and /api/mcp/*, are restricted to loopback-only access. Even an admin-scoped remote token cannot spawn subprocesses or access service management endpoints. This architectural constraint ensures that potentially dangerous operations remain confined to the machine physically running OmniRoute.

Automating Remote Workflows

For CI pipelines or non-interactive scripts, bypass the context system by passing credentials directly via flags. Export the token and target the remote server explicitly:

#!/usr/bin/env bash
export OMNIROUTE_API_KEY="oma_live_XXXXXXXXXXXXXXXX"

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

This approach avoids writing sensitive tokens to disk on ephemeral build agents while maintaining full API functionality within the token’s scope.

Configuring Downstream AI Tools

OmniRoute can populate configuration files for compatible CLIs using the remote server’s model catalog. The omniroute configure command (backed by generators in src/lib/cli-helper/config-generator/) reads the active context’s provider list and writes local config files.

# Configure Codex to use the remote VPS

omniroute setup-codex

# Configure OpenCode with explicit remote flags

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

These commands allow tools like Codex, Claude, and OpenCode to treat your VPS-hosted OmniRoute as an OpenAI-compatible provider without manual URL copying.

Summary

• Remote mode uses HTTP(S) and scoped access tokens to let a local CLI control a VPS-hosted OmniRoute instance.
• Contexts are stored in ~/.omniroute/config.json and managed via omniroute contexts commands.
• The Management API (/api/cli/*) handles authentication and enforces scope-based access control via src/lib/authz/tokenValidator.ts.
• Token scopes (read, write, admin) restrict capabilities; admin is required for provider and OAuth management.
• Security requires HTTPS/Tailnet transport and careful token storage; service management routes are inaccessible remotely to prevent arbitrary code execution.
• Use omniroute setup-* commands to integrate remote models into downstream AI tools automatically.

Frequently Asked Questions

What is the difference between local and remote mode in OmniRoute?

Local mode executes commands against a server running on localhost, typically used during development. Remote mode stores a server URL and bearer token in a local context, causing the CLI to send all requests to that external host. Both modes use the same binary and command syntax; only the target endpoint changes based on the active context.

How do I switch between multiple OmniRoute servers from the same CLI?

Use the omniroute contexts command group. Run omniroute contexts use <name> to activate a saved context, or omniroute contexts use default to return to the local server. You can view all saved contexts with omniroute contexts list and rename them with omniroute contexts rename for easier management.

Can I restrict a token to read-only access for CI pipelines?

Yes. When creating a token via omniroute tokens create --scope read, the server issues a token restricted to GET operations and safe listing commands. According to src/app/api/v1/cli/tokens/, these tokens cannot modify providers, policies, or OAuth configurations, making them safe for automated reporting or monitoring scripts.

Why can't I access service management routes when using remote mode?

Routes under /api/services/* and /api/mcp/* are hardcoded as loopback-only in the OmniRoute source. This security measure prevents a compromised remote token from spawning subprocesses on the server. To manage services, you must execute commands directly on the VPS via SSH or use the local CLI when physically on that machine.

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