Cortex OAuth CLI

A local OAuth helper tool for Cortex that handles authentication for multiple providers on your local machine.

Supported Providers

Provider	Command	Description
Google Antigravity	cortex-oauth google	Vertex AI / Google Cloud AI
Claude Code	cortex-oauth claude	Anthropic Claude API
ChatGPT/Codex	cortex-oauth chatgpt	OpenAI API

Why This Exists

OAuth flows for these providers require a redirect to localhost which can't be done from a remote server. This CLI tool runs on your local machine to:

1. Start a temporary HTTP server on the appropriate localhost port
2. Open your browser to the provider's OAuth page
3. Capture the OAuth callback with authorization code
4. Exchange the code for an access token
5. Output a base64-encoded token string you can paste into Cortex's web UI

Usage

# Google Antigravity (Vertex AI)
cortex-oauth google

# Claude Code (Anthropic)
cortex-oauth claude

# ChatGPT/Codex (OpenAI)
cortex-oauth chatgpt

# Show help
cortex-oauth --help

Alternative Provider Names

Each provider accepts multiple aliases:

• Google: google, antigravity, vertex
• Claude: claude, claude-code, anthropic
• ChatGPT: chatgpt, codex, openai

Flow

┌─────────────────────┐
│   cortex-oauth CLI  │
│  (your local machine)│
└──────────┬──────────┘
           │
           │ 1. Start local server on provider-specific port
           │ 2. Open browser to OAuth page
           ▼
┌─────────────────────┐
│   Provider OAuth    │
│   (in browser)      │
└──────────┬──────────┘
           │
           │ 3. User authenticates
           │ 4. Provider redirects to localhost callback
           ▼
┌─────────────────────┐
│   cortex-oauth CLI  │
│   (captures code)   │
└──────────┬──────────┘
           │
           │ 5. Exchange code for access token (with PKCE)
           │ 6. Output base64 token string
           ▼
┌─────────────────────┐
│   Cortex Web UI     │
│   (paste token)     │
└─────────────────────┘

Provider Ports

Each provider uses a specific localhost port (required by their OAuth configuration):

Provider	Port	Callback Path
Google Antigravity	51121	/oauth-callback
Claude Code	8765	/callback
ChatGPT/Codex	1455	/auth/callback

Building

# Build for development
cargo build -p cortex-oauth

# Build release binary
cargo build -p cortex-oauth --release

# Run directly
cargo run -p cortex-oauth -- google

Security Notes

• All local servers bind only to 127.0.0.1 (localhost) - not accessible from other machines
• PKCE (Proof Key for Code Exchange) is used for all providers
• State parameter is validated to prevent CSRF attacks
• The server shuts down immediately after capturing the token
• Tokens include refresh tokens when provided by the OAuth server

Token Format

The output is a base64-encoded JSON object:

{
  "provider": "google",
  "access_token": "ya29...",
  "refresh_token": "1//..."
}

Copy the entire base64 string and paste it into the Cortex web UI provider configuration.

Dependencies

• tokio - Async runtime
• axum - HTTP server
• reqwest - HTTP client for token exchange
• serde / serde_json - JSON handling
• sha2 / base64 - PKCE code challenge
• open - Open browser

License

MIT OR Apache-2.0