How OmniRoute Remote Mode Works for VPS Deployments

Remote mode lets you run the omniroute CLI locally while the server lives on a remote VPS, with all commands transparently forwarded over HTTP using scoped access tokens.

OmniRoute remote mode solves the problem of managing AI routing infrastructure without running the full stack on your laptop. This guide explains the architecture, token scoping, and deployment patterns used in the diegosouzapw/OmniRoute repository.

Remote Mode Architecture

The architecture splits responsibilities between your local machine and the VPS. The CLI becomes a thin client; the VPS hosts the Next.js API, streaming engine, database, and dashboard.

Component	Role	Implementation
Local CLI	Parses commands, stores remote context	omniroute connect saves URL + token to contexts config
Scoped CLI Token	Short-lived authorization (oma_…)	Defined in src/lib/accessTokens/scopes.ts
Remote Server	API routes, auth, UI, database	Validates tokens in src/server/authz/accessTokenAuth.ts
VPS Runner Scripts	CI/CD VM lifecycle	scripts/vps/release-runner-up.sh and release-runner-down.sh

The Connect Flow

When you run omniroute connect http://<vps-ip>:20128, the CLI:

1. Prompts for or mints a scoped CLI access token
2. Stores the remote base URL and token in ~/.omniroute/contexts.json
3. Prepends the remote URL to all subsequent API calls

The token scope determines which routes you can reach. Remote-scoped tokens cannot access loopback-only endpoints like local OAuth callbacks.

Scoped Token Security Model

OmniRoute uses a three-level scope hierarchy defined in src/lib/accessTokens/scopes.ts:

• worktree — Limited to the current project directory
• remote — Full API access except loopback-only routes
• (default/local) — Unrestricted, but only valid from localhost

The server enforces scope in src/server/authz/policies/management.ts. When a request arrives with a remote token, the policy evaluates scope before any API-key authentication branch. This ordering guarantees that a compromised remote token cannot bypass scope restrictions by presenting additional credentials.

In src/server/authz/accessTokenAuth.ts, the middleware rejects remote tokens that attempt to reach endpoints marked as loopback-only in the route manifest.

Provider Configuration on Remote VPS

Connecting third-party providers (Antigravity, Codex, Grok, etc.) works differently when the server is remote. The docs/guides/REMOTE-MODE.md file documents two supported methods:

Auth helper flow — The helper runs on the VPS and opens a browser on your local machine. The remote token is exchanged through a secure tunnel, never exposing loopback URLs.

Manual token entry — Generate a token from the provider's dashboard and paste it into the remote OmniRoute UI at http://<vps-ip>:20128.

Both flows respect token scoping. The OAuth callback URL remains localhost on the VPS, but remote clients cannot reach it.

Connecting a Local CLI to Remote VPS

# Connect to the remote instance

omniroute connect http://192.168.0.15:20128

# Mint a remote-scoped access token

omniroute token mint --scope remote

# Verify the context was saved

omniroute contexts list

After connecting, standard commands transparently target the VPS:

# Configure a provider using the remote model catalog

omniroute configure codex

# List tokens stored on the remote server (masked)

omniroute tokens list

# Set up OpenCode to route through the VPS

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

CI/CD VPS Runner Integration

The repository includes scripts for testing remote mode in production-like conditions. The VPS runner spins up a dedicated VM for release testing.

# Start the VPS runner and register with GitHub

./scripts/vps/release-runner-up.sh

# The script sets USE_VPS_RUNNER=true when the runner is online

# CI jobs then target this remote environment

# After tests, tear down (or keep running if VPS_ALWAYS_ON=true)

./scripts/vps/release-runner-down.sh

In scripts/vps/release-runner-up.sh, the script polls the GitHub API until the self-hosted runner reports online, then flips the repository variable. This lets workflows conditionally use the VPS runner with:

runs-on: ${{ vars.USE_VPS_RUNNER == 'true' && 'self-hosted' || 'ubuntu-latest' }}

Key Implementation Files

File	Purpose
docs/guides/REMOTE-MODE.md	User-facing remote mode documentation
src/lib/accessTokens/scopes.ts	CLI token scope definitions
src/server/authz/accessTokenAuth.ts	Token validation middleware
src/server/authz/policies/management.ts	Scope enforcement for management routes
src/lib/api/requireManagementAuth.ts	Interceptor for management API auth
scripts/vps/release-runner-up.sh	VPS lifecycle for CI/CD
scripts/vps/release-runner-down.sh	VPS teardown script

Summary

• Remote mode separates the OmniRoute CLI from the server, enabling VPS deployments
• Scoped tokens (worktree, remote) enforce least-privilege access with loopback protection
• The connect flow stores remote context locally; all subsequent commands target the VPS
• Provider auth uses either an auth helper or manual token entry, never exposing localhost
• CI/CD integration via release-runner-up.sh validates remote mode in automated tests

This architecture lets teams run OmniRoute on cheap VPS instances while developers retain the familiar local CLI experience.

Frequently Asked Questions

What is the difference between local and remote token scopes?

Local tokens (default, no explicit scope) work only from localhost and grant full access. Remote-scoped tokens work from any IP but cannot reach loopback-only routes like OAuth callbacks. According to src/lib/accessTokens/scopes.ts, this prevents remote tokens from exploiting local-only endpoints even if stolen.

Can I run multiple OmniRoute CLIs against the same VPS?

Yes. Each CLI maintains its own context in ~/.omniroute/contexts.json. Use omniroute contexts list to see saved connections and omniroute contexts use <name> to switch. Each CLI can mint its own token, and the server tracks them independently in src/server/authz/accessTokenAuth.ts.

Does remote mode encrypt traffic between CLI and VPS?

The implementation expects HTTPS in production. The omniroute connect command accepts any http:// or https:// URL, but the documentation recommends TLS-terminated endpoints. Token transmission follows standard HTTP Authorization header patterns; encryption depends on your VPS configuration.

What happens to my local OmniRoute server when using remote mode?

Nothing. Local and remote modes are independent. The CLI simply changes its API base URL. You can omniroute contexts use local to switch back to localhost:20128. The local server process, if running, continues unaffected.

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