Relay — Universal AI API Proxy

A CLI for managing and hot-switching LLM providers with a built-in HTTP proxy. Works with any AI coding agent (Claude Code, ForgeCode, OpenAI Codex CLI, OpenCode, Cline, Aider, Continue, etc.) and any provider that speaks the Anthropic or OpenAI API.

Supported Providers

Adding a new provider only requires an entry in the provider registry — no code changes needed.

Why Relay?

AI coding agents cache the model name and base URL at session start. Swapping providers mid-session requires a full restart. With relay proxy, you point your agent at a local proxy once and hot-switch providers at any time without restarting.

Key features:

• Agent-agnostic — works with any tool that speaks Anthropic or OpenAI protocol
• Provider-agnostic — transparently routes to 14+ providers with automatic protocol translation
• Hot-switch providers — change between Copilot, OpenAI, Anthropic, Z.AI, or any supported provider without restarting your session
• Auto-rotation — automatically cycle through accounts when quotas are exhausted
• Protocol translation — transparent Anthropic-to-OpenAI translation so agents speaking one protocol can use providers speaking the other
• Usage tracking — real-time quota monitoring with percentage used and reset timers
• Dynamic model discovery — fetch available models from provider APIs, with user-overridable model lists
• Multi-account — add multiple accounts per provider, switch freely

Installation

From GitHub

# Install from main branch — requires git and pnpm
pnpm install -g github:ImBIOS/relay

Option A: Non-interactive (Docker/CI)

# Add accounts with API keys
relay account add --name "[email protected]" --provider zai --key sk-xxx --activate
relay account add --name "[email protected]" --provider minimax --key mmkey-xxx

# Or use relay init for guided onboarding
relay init --providers zai,minimax --zai-api-key sk-xxx --minimax-api-key mmkey-xxx --install-hooks

# Start proxy
relay proxy status   # auto-starts if not running

Option B: GitHub Copilot via OAuth

# Interactive OAuth device flow — opens browser for authentication
relay account login copilot

# Or add with a fine-grained PAT
relay account add --name "[email protected]" --provider copilot --key github_pat_xxx

Option C: Run from source

git clone https://github.com/ImBIOS/relay.git
cd relay
bun install
bun src/run.ts account add   # interactive
bun src/run.ts proxy status

Configuration

Relay exposes a local proxy that any AI agent can connect to. Point your agent at http://127.0.0.1:8787/api/anthropic with any auth token (e.g. relay).

Claude Code

relay init --install-hooks writes the required environment and installs a SessionStart hook automatically.

To configure manually, add to ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "relay",
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8787/api/anthropic"
  }
}

ForgeCode

Add to .forge.toml:

[anthropic]
api_key = "relay"
base_url = "http://127.0.0.1:8787/api/anthropic"

Or use the shell wrapper:

relay hooks forge-setup     # Install wrapper + config
relay hooks forge-setup --uninstall  # Remove

OpenAI Codex CLI

Install the shell wrapper and config:

relay hooks codex-setup     # Install wrapper + ~/.codex/config.toml
relay hooks codex-setup --uninstall  # Remove

After setup, just run codex as usual — Relay handles the rest:

• Sets OPENAI_API_KEY and OPENAI_BASE_URL to route through the proxy
• Starts proxy and rotates accounts on launch
• Configures ~/.codex/config.toml with the right model and provider

To configure manually, set environment variables:

export OPENAI_API_KEY="relay"
export OPENAI_BASE_URL="http://127.0.0.1:8787/api/openai/v1"
codex

OpenCode

Add to opencode.json:

{
  "provider": {
    "anthropic": {
      "apiKey": "relay",
      "baseURL": "http://127.0.0.1:8787/api/anthropic"
    }
  }
}

Any Agent

Any tool that supports custom Anthropic or OpenAI base URLs can use Relay. Set the base URL to http://127.0.0.1:8787/api/anthropic (for Anthropic-protocol agents like Claude Code, ForgeCode) or http://127.0.0.1:8787/api/openai/v1 (for OpenAI-protocol agents like Codex CLI) and use any string as the API key.

Commands

Proxy

Account Management

Models

Monitoring

Auto-Rotation

How It Works

Any AI Agent
(Claude Code, ForgeCode, OpenAI Codex CLI, OpenCode, Cline, Aider, Continue, ...)
        │
        │  POST /api/anthropic/v1/messages  (or /api/openai/v1/chat/completions)
        │  (Authorization: Bearer relay)
        │
  ┌─────▼──────┐
  │ relay proxy │
  │             │
  │  • Auth: replaces token with real API key
  │  • Routing: sends to active provider
  │  • Translation: Anthropic ↔ OpenAI as needed
  │  • Passthrough: OpenAI → OpenAI (Codex CLI)
  │  • Logging: timestamp, model, provider, latency
  └─────┬──────┘
        │
   ┌────┼────────────────┐
   │    │                │
   ▼    ▼                ▼
Z.AI  MiniMax    GitHub Copilot
       │          │
       ▼          ▼
    OpenAI    OpenRouter
    Anthropic  DeepSeek
    Groq       Ollama
    ...        ...

Routing and translation: The proxy routes requests based on the active account's provider. For providers that speak Anthropic protocol (Z.AI, MiniMax, Anthropic), requests pass through directly. For OpenAI-protocol providers (Copilot, OpenAI, DeepSeek, Groq, etc.), the proxy translates between Anthropic and OpenAI wire formats transparently — so any agent can talk to any provider. Requests arriving at /api/openai (from tools like Codex CLI) are forwarded as-is to OpenAI-protocol providers without translation.

Model Management

Relay supports three sources of model definitions, resolved in priority order:

1. User overrides — custom models added via relay models add
2. Cached fetch — models fetched from provider APIs via relay models refresh (cached for 7 days)
3. Built-in static — hardcoded defaults from the provider registry

This means you can always stay current:

• Run relay models refresh to fetch the latest models from providers that support it
• Add custom models with relay models add if a provider releases a new model before Relay is updated
• Reset to defaults with relay models reset at any time

Usage Tracking

Relay fetches real usage data from providers that expose quota APIs:

• GitHub Copilot: Premium interactions, chat, and completions quotas via copilot_internal/user
• Z.AI: Token limits (daily and weekly) with reset timers
• MiniMax: Token usage with quota tracking

$ relay usage

  github-copilot@ImBIOS — GitHub Copilot
  Plan: individual
  Premium Interactions: 67 / 300 (22.4% used)
  Resets at 07:00 on 1 Jun (397h left)

Notes for Docker and CI

• relay account add --name ... --provider ... --key ... is safe for non-interactive environments
• relay init --providers ... --install-hooks sets up everything in one command
• Interactive flows (relay account add, relay account login copilot) require a TTY
• relay account switch <provider> works when the provider resolves to exactly one account

Tech Stack

• Runtime: Bun 1.2.0+
• Language: TypeScript (ESM, strict)
• CLI Framework: oclif + Ink (React-based terminal UI)
• Linting: oxlint + oxfmt (OXC)
• Testing: Bun test runner

Repo Structure

relay/
├── src/
│   ├── commands/
│   │   ├── account/       # add, list, switch, edit, remove, login, migrate
│   │   ├── proxy/         # start, stop, status
│   │   ├── auto/          # enable, disable, status
│   │   ├── hooks/         # session-start, forge-setup, codex-setup, install
│   │   ├── models.tsx     # list, add, remove, refresh, reset
│   │   ├── usage.tsx      # usage tracking
│   │   └── doctor.tsx     # diagnostics
│   ├── config/
│   │   ├── accounts-config.ts     # account management
│   │   ├── provider-registry.ts   # 14 provider definitions
│   │   ├── provider-metadata.ts   # provider metadata helpers
│   │   ├── models-cache.ts        # user-overridable model storage
│   │   └── settings.ts            # legacy config compat
│   ├── proxy/
│   │   ├── server.ts              # HTTP proxy with protocol translation
│   │   └── translators/
│   │       └── anthropic-openai.ts # Anthropic ↔ OpenAI translation
│   ├── providers/
│   │   ├── base.ts        # provider interface
│   │   ├── zai.ts         # Z.AI provider
│   │   ├── minimax.ts     # MiniMax provider
│   │   └── copilot.ts     # GitHub Copilot provider
│   └── utils/             # logger, telemetry, format, validation
└── bin/relay.bundled.js   # optional bundled build

License

See LICENSE