How OmniRoute Remote Mode Works with Scoped Tokens and Antigravity OAuth for VPS

OmniRoute remote mode allows a local CLI or dashboard to securely manage a remote VPS instance using scoped CLI access tokens and Antigravity OAuth for provider authentication.

This guide explains how OmniRoute's distributed architecture enables secure, token-based management of remote servers. Whether you're running OmniRoute on a self-hosted VPS or managing multiple deployments, understanding the scoped token hierarchy and OAuth integration is essential for secure operations.

What Is OmniRoute Remote Mode?

OmniRoute can operate in remote mode, where your local CLI connects to a remote OmniRoute server rather than running the entire stack locally. This architecture separates the control plane (your local interface) from the data plane (the remote server handling LLM inference).

In this configuration:

• The remote server maintains all configuration, API keys, and provider credentials
• Your local client authenticates using scoped CLI access tokens prefixed with oma_
• The token's scope determines which management operations you can perform
• Antigravity OAuth flows are orchestrated through the remote server, not locally

This design lets you run a lightweight OmniRoute instance on resource-constrained devices while delegating heavy inference workloads to a dedicated VPS.

Scoped Token Architecture and Hierarchy

OmniRoute implements a three-level scope hierarchy defined in src/lib/accessTokens/scopes.ts. This hierarchy is strictly enforced and cannot be bypassed.

The Three Scope Levels

Scope	Permissions	Typical Use Case
read	List and inspect resources (models, providers, logs, usage, cost reports)	Monitoring dashboards, cost tracking scripts
write	All read permissions plus configuration changes (add API keys, edit routing combos, install services)	Day-to-day operational management
admin	All write permissions plus sensitive operations (create/revoke tokens, add new providers, configure OAuth)	Initial setup, security administration

The hierarchy is cumulative: admin implies write, and write implies read. This design prevents accidental privilege escalation—a token created with read scope can never perform write operations, even if the bearer attempts to craft manual API requests.

Token Evaluation Pipeline

When a remote-mode request arrives, the access-token evaluator in src/server/authz/accessTokenAuth.ts performs these steps:

1. Extracts the Bearer token from the Authorization header
2. Verifies the token against the database via verifyAccessToken
3. Infers the required scope for the HTTP method and path using inferRequiredScope
4. Validates hierarchy compliance with scopeSatisfies

If any check fails, the server responds with HTTP 403 and an insufficient_scope error. Successful evaluation marks the request as an authorized management call.

All management routes under /api/v1/... enforce this pipeline through src/lib/api/requireManagementAuth.ts, which runs before any API-key-based inference authentication. Loop-back-only routes that spawn local processes are explicitly excluded via the isLocalOnlyPath check.

Antigravity OAuth for Remote VPS Deployments

Antigravity OAuth is OmniRoute's mechanism for obtaining credentials from the Antigravity LLM provider. Unlike local-mode OAuth, remote-mode flows are fully server-orchestrated.

The Remote OAuth Flow

When you run omniroute login antigravity against a remote server, here's what happens:

1. CLI sends request to the remote server's remote-OAuth hint endpoint at src/app/api/oauth/[provider]/[action]/remoteOAuthHint.ts
2. Server builds OAuth URL embedding the current remote host and Antigravity's consent screen parameters
3. CLI receives URL and opens the user's browser for authorization
4. User completes consent on Antigravity's site, which redirects back to the remote OmniRoute instance
5. Remote server stores the resulting access token in its database
6. Scoped token issued — the server creates an oma_-prefixed token (typically admin scope for full management) and returns it to the CLI
7. CLI stores token in the active context for subsequent requests

The stored Antigravity credentials remain on the remote server; your local client never handles raw provider tokens directly. This centralizes credential security on your controlled VPS infrastructure.

Practical Remote Mode Workflow

Initial Connection and Setup

# Connect CLI to remote OmniRoute instance

omniroute connect https://my-vps.example.com

# Authenticate with Antigravity (triggers OAuth flow)

omniroute login antigravity

The connect command establishes the remote endpoint. The login command initiates the OAuth sequence described above, resulting in a scoped token stored in your local CLI context.

Typical Operations by Scope

# Read-scope operations (available with any valid token)

omniroute models list
omniroute usage report --last-7-days

# Write-scope operations (requires write or admin token)

omniroute provider add openai --key $OPENAI_KEY
omniroute combo create fast-gpt4 --providers gpt-4,claude-3-opus

# Admin-scope operations (requires admin token)

omniroute token create --scope read --name "monitoring-script"
omniroute token revoke oma_oldtoken123

Manual API Request Example

The CLI automatically adds the Authorization header. Here's what a raw request looks like:

GET /v1/models HTTP/1.1
Host: my-vps.example.com
Authorization: Bearer oma_1a2b3c4d5e6f7g8h9i0j

An insufficient scope produces:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{ "error": "insufficient_scope", "message": "admin required" }

Security Considerations for VPS Deployments

Several mechanisms protect remote-mode deployments:

• Token prefixing: The oma_ prefix allows quick identification of CLI access tokens in logs and databases
• Scope hierarchy enforcement: scopeSatisfies prevents any scope downgrade attacks
• Path-based exclusions: isLocalOnlyPath blocks remote access to process-spawning routes that could compromise host security
• Database-backed verification: Tokens are validated against persistent storage on every request, enabling immediate revocation

According to the OmniRoute source code, all remote-mode authentication paths in src/lib/api/requireManagementAuth.ts explicitly reject requests that bypass the scoped token evaluator, ensuring no fallback to weaker authentication methods.

Key Implementation Files

File	Purpose
src/lib/accessTokens/scopes.ts	Scope definitions and hierarchy logic
src/server/authz/accessTokenAuth.ts	Token extraction, verification, and scope evaluation
src/lib/api/requireManagementAuth.ts	Remote-mode middleware enforcing token validation
src/app/api/oauth/[provider]/[action]/remoteOAuthHint.ts	OAuth URL generation for remote flows
electron/remoteServerPromptRenderer.js	Desktop app remote connection UI
tests/unit/cli-remote-mode.test.ts	End-to-end remote-mode test validation

Summary

• OmniRoute remote mode enables secure CLI-to-VPS management using scoped tokens prefixed with oma_
• Three scope levels (read, write, admin) enforce strict privilege boundaries
• Antigravity OAuth flows are server-orchestrated: the remote instance handles provider credentials, not the local client
• The access-token evaluator in src/server/authz/accessTokenAuth.ts validates every request through verifyAccessToken, inferRequiredScope, and scopeSatisfies
• Management routes in src/lib/api/requireManagementAuth.ts ensure scoped authentication precedes all other authorization checks

Frequently Asked Questions

Can I use the same scoped token from multiple CLI installations?

Yes. Scoped tokens are stored in the remote server's database and validated on each request. You can use an oma_ token from any device with network access to your VPS. However, tokens are typically created per-client during the omniroute connect flow, so sharing tokens manually is not the intended workflow.

What happens if my token is compromised?

Tokens can be immediately revoked using any client with admin scope: omniroute token revoke oma_compromised. Because verification hits the database on every request (verifyAccessToken), revocation takes effect instantly without waiting for cache expiration.

Does remote mode support OAuth providers other than Antigravity?

The architecture in src/app/api/oauth/[provider]/[action]/remoteOAuthHint.ts uses a dynamic route handler ([provider]) designed for extensibility. While this guide focuses on Antigravity, the same remote-OAuth hint mechanism can be implemented for additional providers by extending the provider-specific logic in that endpoint.

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