# Remote Mode in OmniRoute: Scoped Tokens, Antigravity OAuth, and Context Management Explained

> Master Remote Mode in OmniRoute for secure remote control using scoped tokens and context management. Explore Antigravity OAuth with this comprehensive guide.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: deep-dive
- Published: 2026-08-22

---

**Remote Mode lets developers run OmniRoute on a remote machine (VPS, Tail‑Net, etc.) and control it securely from any local workstation using scoped access tokens and automatic context management.**

OmniRoute is an open-source routing and orchestration platform that supports distributed deployments. **Remote Mode in OmniRoute** enables seamless management of remote instances through a context-aware CLI that handles authentication via scoped JWTs and an integrated Antigravity OAuth helper for headless setups. This architecture ensures that sensitive credentials never leave the client machine while allowing full remote control.

## Understanding Remote Mode Architecture

Remote Mode establishes a secure bridge between your local CLI and a remote OmniRoute instance. According to the implementation in [`docs/guides/REMOTE-MODE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/REMOTE-MODE.md), the workflow relies on three tightly coupled components: a context manager for local state, a scoped token issuance system, and the Antigravity OAuth helper for initial authentication.

The `omniroute connect <host>` command initiates the handshake, authenticating via password to mint a scoped token that encodes specific permissions (admin, write, etc.). This token is then automatically attached to every subsequent API request as an `Authorization: Bearer <token>` header, as implemented in [`src/app/api/cli/whoami/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/cli/whoami/route.ts).

## Scoped Tokens and Context Management

### Token Minting and Scope Levels

The server generates a **scoped JWT** whose claims include the requested permission level. As documented in [`docs/guides/REMOTE-MODE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/REMOTE-MODE.md), supported scopes include `admin` for full control and `write` for restricted CI/CD operations.

When you run `omniroute connect 192.168.0.15`, the server exposes an endpoint at `/api/cli/connect` that validates credentials and returns a token bound to the specific scope. This token is never stored on the server; only the cryptographic signature remains server-side for validation.

### Context Persistence

Contexts are stored locally in `~/.omniroute/contexts.json`. Each context record contains:

- The remote server **base URL**
- The **scoped token** value
- The permission **scope** level

The CLI reads the active context before every command and injects the token automatically. This means you can run `omniroute chat "Explain Remote Mode"` without specifying `--remote` flags once a context is active. The implementation in [`src/app/api/cli/whoami/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/cli/whoami/route.ts) (line 11) demonstrates how the CLI validates these contexts against the remote server.

## Antigravity OAuth Helper for Headless Servers

For remote installs that cannot receive OAuth redirects—such as headless VPS machines—OmniRoute provides a **local-login helper** that bridges the Google OAuth flow.

### How the Local-Login Helper Works

As detailed in [`docs/guides/REMOTE-MODE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/REMOTE-MODE.md) (lines 122-138), the Antigravity OAuth helper executes the following flow:

1. Launches a browser-based Google OAuth flow on the local workstation
2. Captures the callback on a loopback port (`localhost`)
3. Exchanges the authorization code for Antigravity credentials
4. POSTs the resulting credential blob directly to the remote server

This eliminates manual token copy-paste. The helper references client credentials defined in [`open-sse/utils/publicCreds.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/publicCreds.ts) and associates the remote project using logic from [`open-sse/services/antigravityProjectBootstrap.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/antigravityProjectBootstrap.ts).

### Integration with Provider Logic

The [`open-sse/utils/thinkCloseMarker.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/thinkCloseMarker.ts) file lists Antigravity among the providers that affect token-scoped request handling, ensuring that OAuth-acquired credentials respect the same scope boundaries as password-minted tokens.

## Practical CLI Usage Examples

To establish a connection with admin scope:

```bash

# Connect to remote instance and store scoped token in local context

omniroute connect 192.168.0.15

# Prompts for password, mints JWT, saves to ~/.omniroute/contexts.json

```

To view and manage contexts:

```bash

# List all saved contexts (URL, scope, and token-id)

omniroute contexts list

# Generate a write-only token for CI pipelines

omniroute tokens create --scope write

# Returns: oma_live_abcdef123456 (store this in CI secrets)

```

To execute commands against remote servers:

```bash

# Uses active context automatically (no --remote flag needed)

omniroute chat "Show me the current model catalog"

# Ad-hoc remote execution without saved context

omniroute chat --remote https://omni.example.com --api-key oma_live_abcdef123456 \
    "Explain Remote Mode"

```

The Antigravity OAuth helper triggers automatically when connecting to servers without direct OAuth callback capabilities:

```bash

# Triggers local-login helper for Antigravity authentication

omniroute connect 192.168.0.15

# Opens browser, captures redirect, POSTs credentials to remote

```

## Token Security and Revocation

**Scoped tokens are stored only locally** in the contexts file. Removing a context via `omniroute contexts remove` deletes the credential from the workstation, but as noted in [`docs/guides/REMOTE-MODE.md`](https://github.com/diegosouzapw/OmniRoute/blob/main/docs/guides/REMOTE-MODE.md) (lines 427-429), this action **does not revoke the token server-side**.

To fully invalidate a token, you must:

1. Remove the local context to prevent CLI usage
2. Revoke the token via the OmniRoute dashboard or API

This two-step process prevents accidentally leaving active tokens on compromised machines while maintaining an audit trail on the server.

## Summary

- **Remote Mode** enables local CLI control of remote OmniRoute instances through secure context management.
- **Scoped tokens** are JWTs minted by the server (via `/api/cli/connect`) that encode permission levels (admin, write) and are stored only in `~/.omniroute/contexts.json`.
- **Context management** automatically injects the `Authorization: Bearer` header for all CLI requests, eliminating manual token handling.
- **The Antigravity OAuth helper** executes Google OAuth flows locally and POSTs credentials to headless remote servers, avoiding manual token transfer.
- **Token revocation** requires both local context deletion and server-side invalidation through the dashboard.

## Frequently Asked Questions

### What is Remote Mode in OmniRoute?

Remote Mode is a deployment architecture that allows the OmniRoute CLI to control instances running on remote machines (VPS, Tail‑Net, cloud servers) through scoped access tokens. It maintains local context files containing URLs and JWT credentials, enabling seamless switching between multiple remote installations without manual authentication on every command.

### How do scoped tokens work in OmniRoute?

Scoped tokens are JSON Web Tokens generated by the remote server's `/api/cli/connect` endpoint when you run `omniroute connect <host>`. The token payload includes a `scope` claim (such as `admin` or `write`) that restricts permissible actions. The CLI stores this token in `~/.omniroute/contexts.json` and automatically attaches it as a Bearer token in the Authorization header of every API request to that host.

### What is the Antigravity OAuth Helper used for?

The Antigravity OAuth Helper solves the "headless server" problem where a remote OmniRoute instance cannot receive OAuth callbacks. When connecting to such servers, the CLI launches a local browser flow on your workstation, captures the Google OAuth callback on `localhost`, exchanges the code for Antigravity credentials using [`open-sse/utils/publicCreds.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/publicCreds.ts), and securely transmits the resulting blob to the remote server without exposing secrets in terminal output.

### How do I revoke a Remote Mode token?

To revoke a Remote Mode token, you must complete two steps: first, delete the local context using `omniroute contexts remove` to prevent the CLI from using the token, and second, invalidate the token server-side through the OmniRoute dashboard or management API. Simply removing the local context does not invalidate the JWT on the server, meaning the token could still be used if leaked.