docs: recommend API keys over OAuth tokens for automation

Update all examples and documentation to use ANTHROPIC_API_KEY as the
primary authentication method. OAuth tokens are now documented as
appropriate for personal testing and development only.

- Update docker run examples across all READMEs
- Add Terms Considerations section to environment-variables.md
- Clarify auth guidance in main README's Important Considerations
- Reorder env vars to list API key first in .env.example and docker-compose.yml

Author: matthew-petty

.env.example

@@ -6,11 +6,11 @@
 CLAUDE_CODE_GATEWAY_API_KEY=your-secret-api-key
 
 # Claude authentication (one of these is required)
-# Option 1: OAuth token for Claude Max subscription
-CLAUDE_CODE_OAUTH_TOKEN=
-
-# Option 2: Anthropic API key for direct API access
+# Recommended: Anthropic API key for automation
 ANTHROPIC_API_KEY=
 
+# Alternative: OAuth token (Claude Pro/Max) - for personal testing and development only
+# CLAUDE_CODE_OAUTH_TOKEN=
+
 # Gateway server port (optional, default: 3100)
 GATEWAY_PORT=3100

README.md

@@ -49,7 +49,7 @@ Claude Code is that orchestration layer:
 # Start the gateway
 docker run -d -p 3100:3100 \
   -e CLAUDE_CODE_GATEWAY_API_KEY=your-gateway-key \
-  -e CLAUDE_CODE_OAUTH_TOKEN=your-claude-token \
+  -e ANTHROPIC_API_KEY=your-anthropic-api-key \
   ghcr.io/pattern-zones-co/koine:latest
 
 # Make your first request
@@ -101,11 +101,10 @@ console.log(result.text);
 >
 > - **Use Docker**: containers provide essential filesystem and process isolation
 > - **Internal networks only**: deploy on VPN or Docker networks, not public internet
-> - **Know your auth method**:
->   - *API keys* (Anthropic API): pay-per-token, suitable for automation
->   - *OAuth tokens* (Claude Pro/Max): subscription plans may restrict commercial use and automation; review [Anthropic's Consumer Terms](https://www.anthropic.com/legal/consumer-terms)
+> - **Use API keys for automation**: Anthropic API keys are the recommended authentication method. They operate under the [Commercial Terms](https://www.anthropic.com/legal/commercial-terms) which permit programmatic access.
+> - **OAuth tokens for personal use only**: Claude Pro/Max OAuth tokens are appropriate for personal testing and development. For production or shared deployments, use an API key.
 >
-> **You are responsible for compliance with Anthropic's Terms of Service.**
+> See [Environment Variables](docs/environment-variables.md#terms-considerations) for details.
 
 ## Documentation
 

docker-compose.yml

@@ -14,18 +14,18 @@ services:
       HOME: /home/bun
       # Authentication for the gateway API
       CLAUDE_CODE_GATEWAY_API_KEY: ${CLAUDE_CODE_GATEWAY_API_KEY:-}
-      # Claude auth: set CLAUDE_CODE_OAUTH_TOKEN for Max subscription, or ANTHROPIC_API_KEY for API auth
-      # If both are set, OAuth token takes precedence (see cli.ts buildClaudeEnv)
-      CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}
+      # Claude auth: ANTHROPIC_API_KEY recommended for automation (see docs/environment-variables.md)
+      # OAuth tokens are appropriate for personal testing and development only
       ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+      CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}
     volumes:
       # Named volume for Claude CLI data
       - koine-data:/home/bun/.claude
       # WARNING: Bind-mounting ~/.claude is NOT SAFE for production.
       # It exposes credentials AND links all user-scoped Claude Code config
       # (slash commands, skills, MCP servers, etc.) which may be inappropriate.
       # Only use for local development/testing. For production:
-      # - Set CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY in .env
+      # - Set ANTHROPIC_API_KEY in .env (recommended for automation)
       # - Use project-scoped assets only (future: build-time asset mounting)
     # Security hardening
     security_opt:

docs/README.md

@@ -15,7 +15,7 @@
 ```bash
 docker run -d -p 3100:3100 \
   -e CLAUDE_CODE_GATEWAY_API_KEY=your-key \
-  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+  -e ANTHROPIC_API_KEY=your-anthropic-api-key \
   ghcr.io/pattern-zones-co/koine:latest
 
 curl http://localhost:3100/health

docs/environment-variables.md

@@ -10,8 +10,8 @@
 
 | Variable | Description |
 |----------|-------------|
-| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth token (Claude Max). Takes precedence if both set. |
-| `ANTHROPIC_API_KEY` | Anthropic API key |
+| `ANTHROPIC_API_KEY` | Anthropic API key (recommended for automation) |
+| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth token (Claude Pro/Max). See [Terms Considerations](#terms-considerations). |
 
 ## Optional
 
@@ -25,6 +25,13 @@
 # .env
 CLAUDE_CODE_GATEWAY_API_KEY=your-secure-api-key
 ANTHROPIC_API_KEY=sk-ant-...
-# CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token
 GATEWAY_PORT=3100
 ```
+
+## Terms Considerations
+
+**API keys** are the recommended authentication method for Koine and automation use cases. They operate under [Anthropic's Commercial Terms](https://www.anthropic.com/legal/commercial-terms) which explicitly permit programmatic access.
+
+**OAuth tokens** (Claude Pro/Max subscriptions) are appropriate for personal testing and development only. For production or shared deployments, use an API key.
+
+If both are set, the OAuth token takes precedence. For automation, set only `ANTHROPIC_API_KEY`.

packages/gateway/README.md

@@ -9,7 +9,7 @@ This package is not published to npm. Deploy via Docker (pre-built or from sourc
 ```bash
 docker run -d -p 3100:3100 \
   -e CLAUDE_CODE_GATEWAY_API_KEY=your-key \
-  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+  -e ANTHROPIC_API_KEY=your-anthropic-api-key \
   ghcr.io/pattern-zones-co/koine:latest
 ```
 

packages/sdks/python/README.md

@@ -7,7 +7,7 @@ Python SDK for [Koine](https://github.com/pattern-zones-co/koine) — the HTTP g
 ```bash
 docker run -d -p 3100:3100 \
   -e CLAUDE_CODE_GATEWAY_API_KEY=your-key \
-  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+  -e ANTHROPIC_API_KEY=your-anthropic-api-key \
   ghcr.io/pattern-zones-co/koine:latest
 ```
 

packages/sdks/python/examples/README.md

@@ -6,7 +6,7 @@
    ```bash
    docker run -d -p 3100:3100 \
      -e CLAUDE_CODE_GATEWAY_API_KEY=your-key \
-     -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+     -e ANTHROPIC_API_KEY=your-anthropic-api-key \
      ghcr.io/pattern-zones-co/koine:latest
    ```
 

packages/sdks/typescript/README.md

@@ -7,7 +7,7 @@ TypeScript SDK for [Koine](https://github.com/pattern-zones-co/koine) — the HT
 ```bash
 docker run -d -p 3100:3100 \
   -e CLAUDE_CODE_GATEWAY_API_KEY=your-key \
-  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+  -e ANTHROPIC_API_KEY=your-anthropic-api-key \
   ghcr.io/pattern-zones-co/koine:latest
 ```
 

packages/sdks/typescript/examples/README.md

@@ -6,7 +6,7 @@
    ```bash
    docker run -d -p 3100:3100 \
      -e CLAUDE_CODE_GATEWAY_API_KEY=your-key \
-     -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+     -e ANTHROPIC_API_KEY=your-anthropic-api-key \
      ghcr.io/pattern-zones-co/koine:latest
    ```