# OAuth Device Code Flow — PTY Allocation Workaround

## The Problem

`hermes auth add <oauth-provider>` (openai-codex, nous, xai-oauth, etc.) uses the OAuth Device Code flow:
1. CLI prints a URL + verification code
2. CLI polls and waits for browser completion
3. Requires a TTY for the polling phase

Plain `terminal(command="hermes auth add openai-codex")` times out because:
- The command blocks waiting for OAuth completion (minutes)
- PTY allocation isn't set up, so `input()` prompts hang silently

## The Workaround

Use the `script` command to allocate a pseudo-TTY:

```bash
script -q -c "hermes auth add openai-codex --type oauth --no-browser" /dev/null
```

**Flags:**
- `-q` — quiet (suppress `script` banner)
- `-c "..."` — run the command string
- `/dev/null` — don't record to file (just for PTY)

This captures the device code URL + code to stdout, then blocks waiting for OAuth completion.

## Full Pattern for Background OAuth

To start the OAuth flow in background and read the code later:

```bash
# Start in background, write output to file
cd ~/.hermes/hermes-agent
nohup script -q -c "hermes auth add openai-codex --type oauth --no-browser" /dev/null > /tmp/codex_auth.log 2>&1 &

# Wait for output, then read the verification code
sleep 6 && cat /tmp/codex_auth.log
```

Output format:
```
To continue, follow these steps:

  1. Open this URL in your browser:
     https://auth.openai.com/codex/device

  2. Enter this code:
     XXXX-XXXX

Waiting for sign-in... (press Ctrl+C to cancel)
```

## Providers Supporting OAuth Device Code

| Provider | Command |
|----------|---------|
| OpenAI Codex | `hermes auth add openai-codex --type oauth --no-browser` |
| Nous | `hermes auth add nous --type oauth --no-browser` |
| xAI / Grok | `hermes auth add xai-oauth --type oauth --no-browser` |
| Qwen | `hermes auth add qwen-oauth --type oauth --no-browser` |

## Caveats

- **Codes expire** — generated codes are time-limited (~10 minutes). If you wait too long before completing browser auth, the code is invalid and you need to restart.
- **Session persistence** — once completed, tokens are stored in `~/.hermes/auth.json`. Re-running `hermes auth add openai-codex` will find existing credentials and ask whether to reuse them.
- **`--no-browser`** is essential on headless servers — skips the attempt to auto-open a browser (which would fail anyway).
- **ChatGPT Plus ≠ API Key** — OAuth device code flow logs into the user's ChatGPT account for Codex access (model: `openai-codex/gpt-5.4`), but this is NOT an OpenAI API Key and cannot be used as `OPENAI_API_KEY` for tools like `auxiliary.vision`.

## For Vision: API Key Required

The `auxiliary.vision` tool needs an **OpenAI API Key** (`sk-...`), not an OAuth token. If the goal is vision capability:

1. **Option A — API Key** (recommended for vision):
   ```bash
   # Create at https://platform.openai.com/api-keys
   echo "OPENAI_API_KEY=sk-..." >> ~/.hermes/.env
   hermes config set auxiliary.vision.provider openai
   hermes config set auxiliary.vision.model gpt-4o
   hermes gateway restart
   ```

2. **Option B — Codex OAuth** (for Codex model access):
   ```bash
   script -q -c "hermes auth add openai-codex --type oauth --no-browser" /dev/null
   # Complete browser auth, then:
   hermes config set model.provider openai-codex
   hermes config set auxiliary.vision.provider openai-codex
   hermes config set auxiliary.vision.model gpt-4o
   ```
   Note: Codex OAuth tokens are stored in `auth.json` credential pool, separate from API Key auth.