# Lotus Collective AI Gateway: Setup

Paste this whole thing into your AI assistant (Claude Code, Cursor, whatever you use). It has everything needed to get connected and verified.

---

**Task: connect me to the Lotus Collective AI Gateway and prove it works.**

## What this is

All company AI traffic routes through `https://gateway.lotuscollective.ai`. The gateway holds the API keys for OpenAI, Anthropic, and xAI. I don't need my own.

Never send an `Authorization` header or a provider API key. Auth is Cloudflare Access against my Google Workspace account (@lotuscollective.ai).

## Step 1: Install cloudflared

Check first:

```bash
which cloudflared
```

If it's missing, on Mac:

```bash
brew install cloudflared
```

(Windows: `winget install --id Cloudflare.cloudflared`. Linux: grab the package from Cloudflare's downloads page.)

## Step 2: Log in

```bash
cloudflared access login https://gateway.lotuscollective.ai
```

A browser opens. Sign in with the @lotuscollective.ai Google account. The token caches to `~/.cloudflared/` and lasts about 24 hours. When calls start coming back 403, run this again.

## Step 3: Smoke test

Every request needs the Access JWT in a `cf-access-token` header:

```bash
curl -s https://gateway.lotuscollective.ai/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "cf-access-token: $(cloudflared access token -app=https://gateway.lotuscollective.ai)" \
  -d '{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"hello world"}],"max_tokens":20}'
```

## Step 4: Verify all three providers

Don't stop at one call. Ping each provider so we know BYOK is wired up across the board.

| Provider | Endpoint | Notes |
|---|---|---|
| OpenAI | `/openai/v1/chat/completions` | |
| Anthropic | `/anthropic/v1/messages` | needs `anthropic-version: 2023-06-01` |
| xAI | `/grok/v1/chat/completions` | |

`GET /openai/v1/models` lists what's available (136 models as of this writing).

Test with `gpt-4.1-mini`, `gpt-5.5`, `claude-opus-5`, `claude-sonnet-5`, and `grok-4`. Report latency and the response text for each.

## Gotchas that'll eat an hour

**403 with `error code: 1010`.** Cloudflare's bot detection rejecting the client's user agent, not an auth failure. Python's `urllib` and `httpx` defaults get blocked. Override it.

Python with the OpenAI SDK:

```python
import subprocess
from openai import OpenAI

token = subprocess.check_output(
    ["cloudflared", "access", "token", "-app=https://gateway.lotuscollective.ai"],
    text=True).strip()

client = OpenAI(
    base_url="https://gateway.lotuscollective.ai/openai/v1",
    api_key="unused",
    default_headers={"cf-access-token": token, "User-Agent": "curl/8.4.0"},
)

print(client.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "hello world"}],
).choices[0].message.content)
```

**gpt-5 and newer reject `max_tokens`.** Use `max_completion_tokens` instead. Those models also spend tokens reasoning before they answer, so give them room (2000+) or you'll get an empty string back and think something's broken.

**429 means budget, not rate limiting.** Everyone gets $200 per rolling 30 days.

## When it breaks

1. Re-run `cloudflared access login`. Expired token is the usual culprit.
2. Still failing? Check the user agent thing above.
3. Still stuck? Ping Matt.


---

## Service / worker path (brain, DBOS, droplets)

Humans keep using `cloudflared access login` as above. **Engine workers must not.**

Use the Access **service token** `lotus-brain-engine` (Client ID + Client Secret). Never put the secret in chat, git, or Slack.

```bash
curl -s https://gateway.lotuscollective.ai/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "User-Agent: curl/8.4.0" \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID_BRAIN_ENGINE" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET_BRAIN_ENGINE" \
  -H "cf-aig-metadata: {\"lotus.workload\":\"engine\"}" \
  -d '{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"ping"}],"max_tokens":20}'
```

SDK base URLs (unchanged):

| Provider | `base_url` |
|---|---|
| OpenAI | `https://gateway.lotuscollective.ai/openai/v1` |
| Anthropic | `https://gateway.lotuscollective.ai/anthropic/v1` |
| xAI | `https://gateway.lotuscollective.ai/grok/v1` |

Required headers for workers: `CF-Access-Client-Id`, `CF-Access-Client-Secret`, `User-Agent: curl/8.4.0`, and `cf-aig-metadata: {"lotus.workload":"engine"}` (routes spend to the **$5,000 / 30d** engine pool, not the human $200 cap).

Do **not** send provider API keys. GLiNER / local encoders stay off this gateway.