AI Relay

Use your Claude, Gemini, GitHub Copilot, or ChatGPT subscription with any OpenAI-compatible client.

Install

npm install -g ai-relay

Quick Start

relay auth claude
relay start
relay status

Commands

| Command | Description | |---------|-------------| | relay init | Create config file at ~/.relay/config.json | | relay auth <provider> | Authenticate with provider | | relay logout <provider> | Remove authentication | | relay start | Start server (background) | | relay stop | Stop server | | relay restart | Restart server | | relay status | Show status |

Providers

| Provider | Aliases | |----------|---------| | claude | c | | gemini | google, g | | github-copilot | gh | | codex | chatgpt, gpt |

Options

| Option | Description | |--------|-------------| | --foreground, -f | Run in foreground | | --ollama | Enable Ollama API |

Model Format

Use provider:model to explicitly select a provider:

claude:claude-opus-4-5
copilot:gpt-4o
gemini:gemini-2.5-pro
codex:gpt-5

Without prefix, auto-detection is used (backward compatible).

Models

Claude (claude:)

| Alias | Model | |-------|-------| | claude-opus-4-5 | claude-opus-4-5-20251101 | | claude-opus-4-1 | claude-opus-4-1-20250805 | | claude-opus-4 | claude-opus-4-20250514 | | claude-sonnet-4-5 | claude-sonnet-4-5-20250929 | | claude-sonnet-4 | claude-sonnet-4-20250514 | | claude-sonnet-3-7 | claude-3-7-sonnet-20250219 | | claude-haiku-4-5 | claude-haiku-4-5-20251001 | | claude-haiku-3-5 | claude-3-5-haiku-20241022 | | claude-haiku-3 | claude-3-haiku-20240307 |

Full model list: claude-opus-4-5-20251101, claude-opus-4-1-20250805, claude-opus-4-20250514, claude-3-opus-20240229, claude-sonnet-4-5-20250929, claude-sonnet-4-20250514, claude-3-7-sonnet-20250219, claude-haiku-4-5-20251001, claude-3-5-haiku-20241022, claude-3-haiku-20240307

Gemini (gemini:)

| Model | |-------| | gemini-2.5-pro | | gemini-2.5-flash | | gemini-2.5-flash-lite | | gemini-2.0-flash-exp |

Alias: gemini-2.0-flash-lite → gemini-2.5-flash-lite

GitHub Copilot (copilot:)

| Model | |-------| | gpt-4.1 | | gpt-5 | | gpt-5-mini | | gpt-5-codex | | gpt-5.1 | | gpt-5.1-codex | | gpt-5.1-codex-mini | | claude-haiku-4.5 | | claude-sonnet-4 | | claude-sonnet-4.5 | | claude-opus-4.1 | | claude-opus-4.5 | | gemini-2.5-pro | | gemini-3-pro | | grok-code-fast-1 | | raptor-mini |

Codex (codex:)

| Alias | Model | |-------|-------| | gpt-5 | gpt-5 | | gpt-5-codex | gpt-5-codex | | gpt-5-codex-latest | gpt-5-codex | | codex-mini | codex-mini-latest |

Full model list: gpt-5, gpt-5.1, gpt-5-codex, gpt-5.1-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini, codex-mini

Reasoning efforts: append -minimal, -low, -medium, -high, -xhigh to model name.

Dynamic Model List

The model list automatically updates based on authentication state. No server restart required.

• New auth: Run relay auth <provider> → models immediately available
• Logout: Run relay logout <provider> → models immediately removed

Clients calling /v1/models or /api/tags always get the current list of available models.

API Endpoints

| Endpoint | Description | |----------|-------------| | POST /v1/chat/completions | Chat completion | | GET /v1/models | List models (auto-refreshed) | | GET /health | Health check |

Ollama API (with --ollama)

| Endpoint | Description | |----------|-------------| | GET /api/tags | List models | | GET /api/show | Show model | | POST /api/chat | Chat completion | | GET /api/version | Version |

Configuration

Run relay init to create ~/.relay/config.json:

{
  "server": {
    "port": 11489
  },
  "rateLimit": {
    "max": 1000,
    "timeWindowMs": 60000
  },
  "ollama": false,
  "providerPriority": ["claude", "copilot", "gemini", "codex"]
}

| Option | Default | Description | |--------|---------|-------------| | server.port | 11489 | Server port | | rateLimit.max | 1000 | Max requests per time window | | rateLimit.timeWindowMs | 60000 | Rate limit window (ms) | | ollama | false | Enable Ollama API endpoints | | providerPriority | ["claude", "copilot", "gemini", "codex"] | Provider priority order for multi-provider models |

Provider Priority: When a model is available on multiple providers (e.g., claude-opus-4.5 on both Claude and Copilot), the first authenticated provider in the list is used. Use a prefix to force a specific provider: copilot:claude-opus-4.5.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PORT | 11489 | Server port | | HOST | 0.0.0.0 | Bind address | | LOG_LEVEL | info | Log level |

Client Examples

Raycast AI (Ollama)

Requires relay start --ollama

1. Open Raycast Settings → AI → Ollama Host
2. Set Ollama Server URL: http://127.0.0.1:11489
3. Models appear automatically via /api/tags

Python

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:11489/v1", api_key="unused")
response = client.chat.completions.create(
    model="claude:sonnet",
    messages=[{"role": "user", "content": "Hello"}]
)

cURL

curl http://127.0.0.1:11489/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini:pro","messages":[{"role":"user","content":"Hello"}]}'

License

ISC