# How OmniRoute Remote Mode Works for VPS Deployments

> Learn how OmniRoute remote mode works for VPS deployments. Run the CLI locally and forward commands transparently over HTTP with scoped access tokens.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/accessTokens/scopes.ts) |
| **Remote Server** | API routes, auth, UI, database | Validates tokens in [`src/server/authz/accessTokenAuth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/accessTokenAuth.ts) |
| **VPS Runner Scripts** | CI/CD VM lifecycle | [`scripts/vps/release-runner-up.sh`](https://github.com/diegosouzapw/OmniRoute/blob/main/scripts/vps/release-runner-up.sh) and [`release-runner-down.sh`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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

```bash

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

```bash

# 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.

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

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

```

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`docs/guides/REMOTE-MODE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/REMOTE-MODE.md) | User-facing remote mode documentation |
| [`src/lib/accessTokens/scopes.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/accessTokens/scopes.ts) | CLI token scope definitions |
| [`src/server/authz/accessTokenAuth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/accessTokenAuth.ts) | Token validation middleware |
| [`src/server/authz/policies/management.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/policies/management.ts) | Scope enforcement for management routes |
| [`src/lib/api/requireManagementAuth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/api/requireManagementAuth.ts) | Interceptor for management API auth |
| [`scripts/vps/release-runner-up.sh`](https://github.com/diegosouzapw/OmniRoute/blob/main/scripts/vps/release-runner-up.sh) | VPS lifecycle for CI/CD |
| [`scripts/vps/release-runner-down.sh`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.