# How to Set Up OmniRoute Remote Mode for Local CLI on VPS > Learn to set up OmniRoute remote mode for local CLI on your VPS. Connect, mint tokens, and manage your remote server over HTTPS for seamless control. - Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute) - Tags: how-to-guide - Published: 2026-07-21 --- **You can manage a VPS-hosted OmniRoute instance from your local machine by installing the CLI, running `omniroute connect ` 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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. ```bash 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. ```bash 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. ```bash 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: ```bash 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 ` - **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: ```bash 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: ```bash #!/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. ```bash # 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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 ` 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.