# AIRelay

AIRelay is a local OpenAI-compatible HTTP server backed by a ChatGPT subscription login that AIRelay stores independently. It does not require a user-supplied OpenAI platform API key for upstream inference. Instead, it uses the same upstream login protocol that Codex uses while keeping AIRelay auth storage separate from Codex storage.

Clients that call AIRelay should use the relay bearer token as the local client credential they present to AIRelay.

AIRelay is an independent third-party project. It is not affiliated with, endorsed by, or sponsored by OpenAI. Provider and product names are used only to describe compatibility targets and upstream behavior. AIRelay is designed for a single user operating a local relay for personal convenience, not as a shared or resale service.

## Project Summary

- local OpenAI-compatible endpoint
- ChatGPT subscription-backed upstream access
- separate local relay bearer token
- route-level protection for `/v1/*` and `/no-tools/v1/*`
- JSONL traffic logging with redaction
- explicit compatibility limits instead of silent fallback

## First-Run Workflow

Install from a source checkout:

```bash
python -m pip install .
```

Install from a published package:

```bash
python -m pip install airelay
```

1. `airelay init`
   - writes `~/.config/airelay/config.toml` if needed
   - creates `~/.airelay/relay-token` if needed
   - reveals the token only when it was newly created
2. `airelay login`
   - creates an AIRelay-owned ChatGPT subscription session
3. `airelay serve --port 8080`
   - starts the protected local server
   - fails fast if bearer auth is enabled but no relay token is configured
   - prints the client base URL, token file path, and required `Authorization` header shape

Inspect current state with:

```bash
airelay status
```

The CLI defaults to readable terminal output. Use `--json` on `airelay init`, `airelay status`, `airelay logout`, `airelay token show`, or `airelay token rotate` when you need machine-readable output.

Show the current relay token with:

```bash
airelay token show
```

Rotate the relay token with:

```bash
airelay token rotate
```

Smoke tests:

```bash
curl http://127.0.0.1:8080/healthz
curl http://127.0.0.1:8080/v1/relay/status \
  -H 'authorization: Bearer YOUR_AIRELAY_TOKEN'
```

## Client Configuration

- base URL: `http://127.0.0.1:8080/v1`
- client credential: the AIRelay relay token

Standard OpenAI SDKs work because they send `Authorization: Bearer <api-key>`.

## Verified Compatibility Boundary

- inference upstream: `https://chatgpt.com/backend-api/codex`
- subscription-status upstream: `https://chatgpt.com/backend-api/wham/usage`
- non-stream responses are reconstructed from streamed upstream events
- `store=true` is rejected
- empty instructions are adapted to `"."`
- local text and JSON-like files up to 1 MB can be inlined
- local image files can be expanded into `input_image`
- local uploads are capped at 32 MiB per file and 256 MiB total by default
- embeddings, image generation, audio, and realtime routes currently return explicit `501 unsupported_error`

## Relay Security

- default listener: `127.0.0.1:8080`
- protected routes: `/v1/*` and `/no-tools/v1/*`
- public liveness: `GET /healthz`
- protected diagnostics: `GET /v1/relay/status`
- relay token file: `~/.airelay/relay-token`
- default request rate limit: `120` requests/minute per IP
- default burst: `40`
- default concurrent-request cap: `8` per IP
- default repeated-auth-failure block: `8` bad attempts in `300` seconds -> `900` second block

Security-relevant events are written to the normal hourly log files. Raw bearer tokens are not written to logs.

## Important Paths

- config: `~/.config/airelay/config.toml`
- data dir: `~/.airelay`
- logs: `~/.airelay/logs`
- upstream auth fallback file: `~/.airelay/auth.json`
- server token override: `AIRELAY_BEARER_TOKEN` or `--bearer-token-file`

## Documentation Map

- `README.md`
  - overview, quick start, supported routes, security defaults, and publication surface
- `docs/getting-started.md`
  - first-run setup and basic commands
- `docs/configuration.md`
  - config file layout, env overrides, and important paths
- `docs/security.md`
  - route protection, rate limits, token rotation, and logging
- `DISCLAIMER.md`
  - independence, non-endorsement, and intended single-user local use
- `docs/api.md`
  - supported routes and explicit unsupported routes
- `docs/architecture.md`
  - package boundaries and request flow
- `docs/subscription-status.md`
  - normalized subscription-status payload
- `docs/faq.md`
  - common usage and policy questions
- `docs/troubleshooting.md`
  - auth, token, and rate-limit recovery
- `docs/adr/README.md`
  - ADR index

## Python Package Surface

- `airelay.config`
  - config resolution, local paths, token bootstrap
- `airelay.security`
  - bearer-token enforcement and in-memory abuse controls
- `airelay.auth`
  - AIRelay-owned upstream ChatGPT subscription auth and refresh
- `airelay.backend`
  - upstream inference and usage calls
- `airelay.transforms`
  - OpenAI-shape request/response translation
- `airelay.store`
  - local files and local conversation state
- `airelay.traffic`
  - redacted JSONL traffic logging
