Skip to content

Getting Started

This guide covers the CLI/server install. If you prefer a GUI, the desktop app (macOS, Windows, Linux) wraps the same relay with a system tray, dashboard, and one-click sign-in — see desktop/README.md and the README's install section.

Install

From a source checkout:

python -m pip install .

From PyPI:

python -m pip install airelays

Initialize AIRelays

airelays init

This prepares:

  • config: ~/.config/airelays/config.toml
  • data dir: ~/.airelays
  • logs dir: ~/.airelays/logs
  • relay token: ~/.airelays/relay-token

Show the current relay token at any time:

airelays token show

OpenAI Runtime

Log in:

airelays login

On a server or over SSH (no local browser), use device-code login — you approve the sign-in from a browser on any other device:

airelays login --device

airelays login selects the device flow automatically on SSH sessions and displayless Linux. The browser flow's URL only works in a browser on the same machine as the relay (its redirect targets localhost:1455 there).

You can enroll several of your own OpenAI accounts: running airelays login again with a different account adds it alongside the first, and the relay balances across them (see the README's "Multiple OpenAI Accounts" section). Sign an account out with airelays logout <email>; manage order and capacity holds with airelays accounts.

Start the server:

airelays doctor
airelays serve --host 127.0.0.1 --port 8080

Verify:

curl http://127.0.0.1:8080/v1/models \
  -H 'authorization: Bearer YOUR_AIRELAYS_TOKEN'

curl http://127.0.0.1:8080/v1/chat/completions \
  -H 'authorization: Bearer YOUR_AIRELAYS_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Reply with exactly: OPENAI AIRelays OK"}]
  }'

OpenAI Open Local Relay Mode

airelays init --no-auth
airelays login
airelays serve --no-auth --host 127.0.0.1 --port 8080

In this mode AIRelays does not require Authorization on /v1/*. Open local relay mode applies to all enabled providers, including the Claude runtime.

Claude Runtime

Browser-based local Claude login:

claude auth login --claudeai

Headless Claude login — claude setup-token needs a browser, so run it on any machine that has one, then carry the token to the server:

# on a machine with a browser:
claude setup-token

# on the server:
airelays init
airelays claude set-token   # paste the token; stored 0600, survives restarts

Exporting CLAUDE_CODE_OAUTH_TOKEN also works, but it does not survive service managers (systemd, docker) or reboots.

Sign Claude out completely (removes the stored token and runs claude auth logout, which signs out every tool using the claude CLI on this machine):

airelays claude logout

Start AIRelays with the Claude runtime enabled:

airelays serve --host 127.0.0.1 --port 8080

Verify:

curl http://127.0.0.1:8080/v1/chat/completions \
  -H 'authorization: Bearer YOUR_AIRELAYS_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude:sonnet",
    "messages": [{"role": "user", "content": "Reply with exactly: CLAUDE AIRelays OK"}]
  }'

Current Claude limits:

  • local-only
  • loopback-only
  • bearer-auth-required
  • text-only
  • stateless

Status

Inspect relay and provider readiness:

airelays status

Run local setup checks plus live upstream probes:

airelays doctor

airelays doctor checks config, relay-token state, OpenAI login readiness, upstream /models, a tiny /responses smoke request, and Claude readiness when the Claude runtime is enabled. Use airelays doctor --skip-response to skip the response smoke request.

List every model id the running relay accepts, grouped by provider:

airelays models

Machine-readable output:

airelays status --json
airelays doctor --json
airelays models --json

airelays status shows:

  • relay config and token state
  • OpenAI runtime readiness
  • Claude runtime readiness when enabled
  • next recommended commands

Provider Routing

  • models starting with claude: use the Claude runtime when it is enabled
  • other model ids use the OpenAI runtime when it is enabled
  • AIRelays rejects requests when the selected runtime is disabled or the route is outside that runtime's published subset

Client Configuration

Base URL:

http://127.0.0.1:8080/v1

Standard OpenAI SDKs can use the AIRelays relay token through their normal api_key field when the base_url points at AIRelays.

Example shell setup:

export OPENAI_BASE_URL='http://127.0.0.1:8080/v1'
export AIRELAYS_TOKEN="$(tr -d '\n' < ~/.airelays/relay-token)"

Subscription Status

OpenAI subscription usage:

curl http://127.0.0.1:8080/v1/subscription/status \
  -H 'authorization: Bearer YOUR_AIRELAYS_TOKEN'

Claude subscription usage (same normalized shape):

curl 'http://127.0.0.1:8080/v1/subscription/status?provider=claude' \
  -H 'authorization: Bearer YOUR_AIRELAYS_TOKEN'

See Subscription Status for multi-account parameters and the payload shape.