agent-relay 1.0.22 → 1.2.0

package/docs/CLOUD-ONBOARDING-DESIGN.md

@@ -0,0 +1,1983 @@
+# Agent Relay Cloud - Onboarding Design
+
+## Overview
+
+Agent Relay supports two deployment models. **Authentication is always handled by Agent Relay Cloud** - users don't self-host the auth system.
+
+### Deployment Models
+
+**Model 1: Cloud Hosted** - We run everything
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    AGENT RELAY CLOUD                            │
+│                                                                 │
+│   User connects accounts → We handle everything else           │
+│                                                                 │
+│   ┌────────────┐  ┌────────────┐  ┌────────────┐              │
+│   │  Provider  │  │   Agent    │  │ Dashboard  │              │
+│   │   Auth     │  │ Execution  │  │  & Logs    │              │
+│   └────────────┘  └────────────┘  └────────────┘              │
+│                         ▲                                       │
+│                         │                                       │
+│   ┌────────────┐  ┌─────┴──────┐                               │
+│   │  GitHub    │──│   Cloned   │                               │
+│   │  Webhooks  │  │   Repos    │                               │
+│   └────────────┘  └────────────┘                               │
+│                                                                 │
+└────────────────────────────────────────────────────────────────┘
+```
+
+**Model 2: Self-Hosted** - User brings their own servers, auth via cloud
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    AGENT RELAY CLOUD                            │
+│                                                                 │
+│   ┌────────────┐  ┌────────────┐  ┌────────────┐              │
+│   │  Provider  │  │ Dashboard  │  │   Team     │              │
+│   │ Auth/Vault │  │  & Logs    │  │ Management │              │
+│   └─────┬──────┘  └─────▲──────┘  └────────────┘              │
+└─────────┼───────────────┼──────────────────────────────────────┘
+          │ Credentials   │ Sync
+          ▼               │
+┌─────────────────────────┴──────────────────────────────────────┐
+│                 USER'S INFRASTRUCTURE                           │
+│                                                                 │
+│   ┌────────────┐  ┌────────────┐  ┌────────────┐              │
+│   │agent-relay │  │   Agents   │  │   Repos    │              │
+│   │  daemon    │  │  (claude,  │  │  (local)   │              │
+│   │            │  │   codex)   │  │            │              │
+│   └────────────┘  └────────────┘  └────────────┘              │
+│                                                                 │
+│   User's VMs, Kubernetes, containers, or bare metal            │
+└────────────────────────────────────────────────────────────────┘
+```
+
+### Feature Comparison
+
+| Feature | Cloud Hosted | Self-Hosted |
+|---------|--------------|-------------|
+| **Provider auth** | ✅ Cloud (device flow) | ✅ Cloud (device flow) |
+| **Credential vault** | ✅ Cloud | ✅ Cloud → synced to user's infra |
+| **Dashboard** | ✅ Cloud | ✅ Cloud (synced from user's infra) |
+| **Team features** | ✅ Full | ✅ Full |
+| **Agent execution** | Our servers | User's servers |
+| **Repos** | Cloned to cloud | User clones locally |
+| **Compute costs** | Included in plan | User pays own infra |
+| **Data locality** | Our cloud regions | User's choice |
+
+### When to Use Each
+
+**Cloud Hosted** - Best for:
+- Teams wanting zero infrastructure management
+- Quick start - no servers to provision
+- Smaller teams without dedicated DevOps
+- CI/CD integration with GitHub Actions
+
+**Self-Hosted** - Best for:
+- Enterprises requiring compute in specific regions/clouds
+- Teams with existing Kubernetes/container infrastructure
+- Cost optimization for high-volume usage
+- Custom security requirements (VPC, firewall rules)
+- GPU workloads on specialized hardware
+
+---
+
+## Cloud Hosted Mode
+
+Agent Relay Cloud (fully hosted) provides:
+- Automatic server provisioning with supervisor
+- GitHub repository integration
+- Multi-provider agent authentication via device flow
+- Team management and collaboration
+- Centralized dashboard and logs
+
+---
+
+## Self-Hosted Mode
+
+For users running agent-relay on their own infrastructure. **Authentication happens via Agent Relay Cloud servers** - users connect to our infrastructure to run the browser-based auth flows.
+
+### Why Self-Hosted Has More Friction (Intentional)
+
+Self-hosted requires extra steps compared to cloud-hosted:
+
+| Step | Cloud Hosted | Self-Hosted |
+|------|--------------|-------------|
+| 1. Sign up | GitHub OAuth | GitHub OAuth |
+| 2. Connect providers | Click "Login with X" | Connect to cloud server, then "Login with X" |
+| 3. Select repos | Select from list | Clone repos locally |
+| 4. Start agents | Automatic | Install agent-relay, configure, start |
+| 5. View dashboard | Just visit URL | Logs sync to cloud dashboard |
+
+**This is intentional** - cloud-hosted should be the path of least resistance.
+
+### Self-Hosted Auth Flow
+
+Since Claude Code and Codex require browser-based OAuth, self-hosted users must connect to our cloud to authenticate:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  SELF-HOSTED AUTHENTICATION                                      │
+│                                                                  │
+│  User's Server                    Agent Relay Cloud              │
+│  ─────────────                    ─────────────────              │
+│                                                                  │
+│  1. agent-relay cloud login                                     │
+│           │                                                      │
+│           │ ──────────────────────────────────────────────────> │
+│           │         Connect to cloud auth service               │
+│           │                                                      │
+│           │                       2. Cloud opens browser         │
+│           │                          to provider (Anthropic)    │
+│           │                               │                      │
+│           │                               ▼                      │
+│           │                       3. User logs in,               │
+│           │                          authorizes                  │
+│           │                               │                      │
+│           │                               ▼                      │
+│           │                       4. Tokens stored               │
+│           │                          in cloud vault              │
+│           │                                                      │
+│           │ <────────────────────────────────────────────────── │
+│           │         Sync encrypted credentials                  │
+│           ▼                                                      │
+│  5. Credentials cached locally                                  │
+│     (encrypted, auto-refresh via cloud)                         │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Setup Flow
+
+```bash
+# On user's server
+npm install -g agent-relay
+
+# Connect to cloud - opens browser on YOUR machine (not server)
+# via a temporary secure tunnel
+agent-relay cloud login
+# → Opens: https://relay.cloud/auth/remote?session=abc123
+# → You authenticate in your browser
+# → Credentials sync to your server
+
+# Connect providers (each opens browser via cloud)
+agent-relay cloud connect anthropic
+agent-relay cloud connect openai
+
+# Start daemon - credentials synced from cloud
+agent-relay up
+```
+
+### CLI Experience
+
+```
+$ agent-relay cloud login
+
+  To authenticate, open this URL in your browser:
+
+  ┌────────────────────────────────────────────────────────────┐
+  │  https://relay.cloud/auth/remote?session=xK9mPq2R         │
+  └────────────────────────────────────────────────────────────┘
+
+  Or scan this QR code:
+  ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
+  █ ▄▄▄▄▄ █ █ ▄▄█
+  █ █   █ █▄▄  ▀█
+  █ █▄▄▄█ █ ▄▀▀▄█
+  ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+
+  ⏳ Waiting for authentication...
+     Session expires in 9:45
+
+  ✅ Authenticated as user@example.com
+
+  Connected providers:
+  • Anthropic (Claude)  ❌ Not connected
+  • OpenAI (Codex)      ❌ Not connected
+
+  To connect providers:
+    agent-relay cloud connect anthropic
+
+$ agent-relay cloud connect anthropic
+
+  To connect Anthropic, open this URL in your browser:
+
+  ┌────────────────────────────────────────────────────────────┐
+  │  https://relay.cloud/connect/anthropic?session=yL8nQr3S   │
+  └────────────────────────────────────────────────────────────┘
+
+  ⏳ Waiting for authorization...
+
+  ✅ Anthropic connected!
+     Logged in as: claude-user@example.com
+     Plan: Claude Pro
+
+  Credentials synced to this server.
+  Run 'agent-relay up' to start.
+```
+
+### Why This Approach
+
+1. **Auth happens on cloud** - Browser-based OAuth works because it runs on our servers
+2. **Credentials sync down** - Encrypted tokens pushed to user's server
+3. **More steps than cloud** - Intentional friction encourages cloud adoption
+4. **Still requires cloud** - Users can't fully disconnect from our service
+5. **Refresh via cloud** - Token refresh happens through our service, maintaining dependency
+
+### Credential Sync Architecture
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    AGENT RELAY CLOUD                            │
+│                                                                 │
+│   ┌──────────────────────────────────────────────────────┐     │
+│   │  Credential Vault (encrypted)                        │     │
+│   │  ┌──────────┐  ┌──────────┐  ┌──────────┐           │     │
+│   │  │Anthropic │  │  OpenAI  │  │  Google  │           │     │
+│   │  │  tokens  │  │  tokens  │  │  tokens  │           │     │
+│   │  └────┬─────┘  └────┬─────┘  └────┬─────┘           │     │
+│   └───────┼─────────────┼─────────────┼─────────────────┘     │
+│           └─────────────┼─────────────┘                        │
+│                         │                                       │
+│                         ▼ Encrypted sync (TLS + E2E)           │
+└─────────────────────────┼───────────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────────┐
+│                 USER'S INFRASTRUCTURE                            │
+│                                                                  │
+│   ┌──────────────────────────────────────────────────────────┐  │
+│   │  agent-relay daemon                                      │  │
+│   │                                                          │  │
+│   │  ┌────────────────────────────────────────────────────┐ │  │
+│   │  │  Local credential cache (encrypted, auto-refresh) │ │  │
+│   │  └────────────────────────────────────────────────────┘ │  │
+│   │                         │                                │  │
+│   │              ┌──────────┼──────────┐                    │  │
+│   │              ▼          ▼          ▼                    │  │
+│   │         ┌────────┐ ┌────────┐ ┌────────┐               │  │
+│   │         │ claude │ │ codex  │ │ gemini │               │  │
+│   │         │ agent  │ │ agent  │ │ agent  │               │  │
+│   │         └────────┘ └────────┘ └────────┘               │  │
+│   └──────────────────────────────────────────────────────────┘  │
+│                                                                  │
+│   Logs synced back to cloud dashboard                           │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Provider Authentication Architecture
+
+### Design Principle: Login-Only Authentication
+
+**No API keys in the UI** - Users authenticate via login flows, not by pasting keys. This provides:
+
+- **Better security**: No keys to leak, rotate, or manage
+- **Consistent UX**: Always "Login with X" buttons
+- **Account linking**: Users authenticate with their existing provider accounts
+- **Automatic token refresh**: Where supported
+
+### Provider Authentication Reality Check
+
+Different providers have different OAuth maturity levels. Notably, **both Claude Code and
+OpenAI Codex** use browser-based OAuth that doesn't support headless/cloud environments well:
+
+| Provider | Auth Flow | Status | Notes |
+|----------|-----------|--------|-------|
+| Claude/Anthropic | Browser OAuth | ⚠️ Device Flow | Opens browser, no redirect URI support |
+| OpenAI/Codex | Browser OAuth | ⚠️ Device Flow | Opens browser for ChatGPT login |
+| Google/Gemini | OAuth 2.0 | ✅ Redirect | Standard Google OAuth with redirect |
+| GitHub Copilot | OAuth 2.0 | ✅ Redirect | Via GitHub OAuth (auto from signup) |
+| Azure OpenAI | OAuth 2.0 | ✅ Redirect | Via Microsoft Entra ID |
+| Local/Self-hosted | None | ✅ N/A | Just endpoint URL |
+
+**Key insight**: The two most popular coding agents (Claude Code and Codex) both require
+device flow or similar workarounds for cloud/headless environments. Both have open GitHub
+issues requesting proper headless auth support:
+- [anthropics/claude-code#7100](https://github.com/anthropics/claude-code/issues/7100)
+- [openai/codex#2798](https://github.com/openai/codex/issues/2798)
+
+### Device Flow Authentication Strategy (Claude + Codex)
+
+Both Claude Code and OpenAI Codex use browser-based OAuth that stores tokens locally:
+- **Claude Code**: `claude /login` → opens browser → stores in `~/.claude/.credentials.json`
+- **Codex**: `codex` → opens browser for ChatGPT → stores in `~/.codex/`
+
+For a cloud environment, we need a **device authorization flow** (RFC 8628):
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Agent Relay Cloud - Claude Code Auth Flow                       │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Step 1: User clicks "Login with Anthropic" in our dashboard    │
+│          ↓                                                       │
+│  Step 2: Opens popup/redirect to Anthropic's OAuth              │
+│          (same flow as `claude /login`)                          │
+│          ↓                                                       │
+│  Step 3: User authenticates with Anthropic                      │
+│          ↓                                                       │
+│  Step 4: Anthropic redirects back with auth token               │
+│          ↓                                                       │
+│  Step 5: We store encrypted token in credential vault           │
+│          ↓                                                       │
+│  Step 6: When spawning agents, inject token via:                │
+│          - ANTHROPIC_AUTH_TOKEN env var, or                     │
+│          - Mount equivalent of ~/.claude/.credentials.json      │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Note**: This requires Anthropic to support redirect-based OAuth (vs device-only flow). If not available, fallback options:
+
+1. **Device Authorization Flow**: Display code, user enters at anthropic.com
+2. **Credential File Upload**: User runs `/login` locally, uploads credential file
+3. **API Key (hidden)**: Accept API key but label it as "Access Token" for consistent UX
+
+### Proposed Solution: Provider Credentials Vault
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Agent Relay Cloud                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐       │
+│  │   GitHub     │    │  Provider    │    │   Secrets    │       │
+│  │   OAuth      │    │  Connector   │    │   Vault      │       │
+│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘       │
+│         │                   │                   │                │
+│         ▼                   ▼                   ▼                │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │                  Onboarding Flow                         │    │
+│  │  1. Sign up (GitHub OAuth)                              │    │
+│  │  2. Connect repositories                                │    │
+│  │  3. Add agent providers                                 │    │
+│  │  4. Configure teams                                     │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Onboarding Flow Design
+
+### Step 1: Sign Up via GitHub OAuth
+
+```
+┌─────────────────────────────────────────────┐
+│         Welcome to Agent Relay Cloud         │
+│                                             │
+│  Orchestrate AI agents across your repos    │
+│                                             │
+│  ┌─────────────────────────────────────┐   │
+│  │  🔗 Continue with GitHub            │   │
+│  └─────────────────────────────────────┘   │
+│                                             │
+│  By signing up, you agree to our Terms     │
+└─────────────────────────────────────────────┘
+```
+
+**Why GitHub first?**
+- Natural auth for developers
+- Immediate access to repo list
+- Repository permissions already defined
+- GitHub Apps for webhook integration
+
+### Step 2: Connect Repositories
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Select Repositories                                         │
+│                                                              │
+│  Which repositories should Agent Relay manage?              │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ 🔍 Search repositories...                              │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  ☑️  acme/frontend          ⭐ 234   Updated 2 hours ago    │
+│  ☑️  acme/backend-api       ⭐ 156   Updated 1 day ago      │
+│  ☐  acme/docs              ⭐ 45    Updated 3 days ago      │
+│  ☐  acme/mobile-app        ⭐ 89    Updated 1 week ago      │
+│                                                              │
+│  ┌──────────────┐  ┌──────────────────────────────────────┐ │
+│  │    Back      │  │  Continue with 2 repositories  →    │ │
+│  └──────────────┘  └──────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**What happens behind the scenes:**
+- Install GitHub App on selected repos
+- Clone repos to cloud workspace
+- Detect existing `.claude/agents/` or `teams.json` configs
+- Set up webhooks for PR/issue events
+
+### Step 3: Add Agent Providers (The Key Step)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Connect Your AI Providers                                       │
+│                                                                  │
+│  Agent Relay works with multiple AI providers. Connect the      │
+│  ones you want to use:                                          │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  ANTHROPIC                                                  ││
+│  │  Claude Code                                                ││
+│  │  ⚡ Recommended for code tasks                              ││
+│  │                                                             ││
+│  │  ┌─────────────────────────────────────────────────────┐   ││
+│  │  │  🔐  Login with Anthropic                           │   ││
+│  │  └─────────────────────────────────────────────────────┘   ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  OPENAI                                                     ││
+│  │  Codex, ChatGPT                                             ││
+│  │  Good for diverse tasks                                     ││
+│  │                                                             ││
+│  │  ┌─────────────────────────────────────────────────────┐   ││
+│  │  │  🔐  Login with OpenAI                              │   ││
+│  │  └─────────────────────────────────────────────────────┘   ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  GOOGLE                                                     ││
+│  │  Gemini                                                     ││
+│  │  Multi-modal capabilities                                   ││
+│  │                                                             ││
+│  │  ┌─────────────────────────────────────────────────────┐   ││
+│  │  │  🔐  Login with Google                              │   ││
+│  │  └─────────────────────────────────────────────────────┘   ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  GITHUB COPILOT                              ✓ Connected    ││
+│  │  Already connected via your GitHub account                  ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  + Add Self-Hosted Provider                                 ││
+│  │  Ollama, LM Studio, or other local tools                    ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+│  You can always add more providers later in Settings            │
+│                                                                  │
+│  ┌──────────────┐  ┌──────────────────────────────────────────┐ │
+│  │    Skip      │  │  Continue  →                            │ │
+│  └──────────────┘  └──────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+#### OAuth Login Flow
+
+When user clicks "Login with [Provider]":
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                                                              │
+│       ┌─────────────────────────────────────────┐           │
+│       │          provider-name.com              │           │
+│       ├─────────────────────────────────────────┤           │
+│       │                                         │           │
+│       │     Sign in to Anthropic                │           │
+│       │                                         │           │
+│       │  ┌───────────────────────────────────┐ │           │
+│       │  │ email@example.com                 │ │           │
+│       │  └───────────────────────────────────┘ │           │
+│       │  ┌───────────────────────────────────┐ │           │
+│       │  │ ••••••••••••                      │ │           │
+│       │  └───────────────────────────────────┘ │           │
+│       │                                         │           │
+│       │  ┌───────────────────────────────────┐ │           │
+│       │  │         Sign In                   │ │           │
+│       │  └───────────────────────────────────┘ │           │
+│       │                                         │           │
+│       │  Or continue with:                      │           │
+│       │  [Google] [GitHub] [SSO]               │           │
+│       │                                         │           │
+│       └─────────────────────────────────────────┘           │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+After login, authorization consent:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                                                              │
+│       ┌─────────────────────────────────────────┐           │
+│       │                                         │           │
+│       │     Authorize Agent Relay Cloud         │           │
+│       │                                         │           │
+│       │  Agent Relay Cloud wants to:            │           │
+│       │                                         │           │
+│       │  ✓ Run AI agents on your behalf         │           │
+│       │  ✓ Access your usage quota              │           │
+│       │  ✓ View your account info               │           │
+│       │                                         │           │
+│       │  Signed in as: user@example.com         │           │
+│       │                                         │           │
+│       │  ┌─────────────┐  ┌─────────────────┐  │           │
+│       │  │   Cancel    │  │   Authorize     │  │           │
+│       │  └─────────────┘  └─────────────────┘  │           │
+│       │                                         │           │
+│       └─────────────────────────────────────────┘           │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+After authorization, redirect back with success:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Connect Your AI Providers                                       │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  ANTHROPIC                                   ✓ Connected    ││
+│  │  Claude Code                                                ││
+│  │  Logged in as claude-user@example.com                       ││
+│  │                                             [Disconnect]    ││
+│  └─────────────────────────────────────────────────────────────┘│
+│  ...                                                            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Device Authorization Flow (RFC 8628)
+
+This is the **primary authentication method** for Claude Code and OpenAI Codex, since neither
+supports standard OAuth redirect flows for third-party cloud applications.
+
+### How Device Flow Works
+
+```
+┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
+│  Agent Relay     │      │   Provider       │      │   User's         │
+│  Cloud           │      │   Auth Server    │      │   Browser        │
+└────────┬─────────┘      └────────┬─────────┘      └────────┬─────────┘
+         │                         │                         │
+         │  1. POST /device/code   │                         │
+         │  {client_id, scope}     │                         │
+         │ ───────────────────────>│                         │
+         │                         │                         │
+         │  {device_code,          │                         │
+         │   user_code: "ABCD-1234"│                         │
+         │   verification_uri,     │                         │
+         │   expires_in: 900}      │                         │
+         │ <───────────────────────│                         │
+         │                         │                         │
+         │  Display code to user   │                         │
+         │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─>│
+         │                         │                         │
+         │                         │  2. User visits URL     │
+         │                         │  & enters user_code     │
+         │                         │<────────────────────────│
+         │                         │                         │
+         │                         │  3. User authenticates  │
+         │                         │  & authorizes app       │
+         │                         │<────────────────────────│
+         │                         │                         │
+         │  4. POST /token         │                         │
+         │  {device_code}          │                         │
+         │  (polling every 5s)     │                         │
+         │ ───────────────────────>│                         │
+         │                         │                         │
+         │  "authorization_pending"│                         │
+         │ <───────────────────────│  (keep polling...)      │
+         │                         │                         │
+         │  5. POST /token         │                         │
+         │ ───────────────────────>│                         │
+         │                         │                         │
+         │  {access_token,         │                         │
+         │   refresh_token}        │                         │
+         │ <───────────────────────│                         │
+         │                         │                         │
+```
+
+### Provider-Specific Device Flow URLs
+
+| Provider | Device Code URL | Token URL | Verification URL |
+|----------|-----------------|-----------|------------------|
+| Anthropic | `api.anthropic.com/oauth/device/code` | `api.anthropic.com/oauth/token` | `console.anthropic.com/device` |
+| OpenAI | `auth.openai.com/device/code` | `auth.openai.com/oauth/token` | `auth.openai.com/device` |
+| Google | `oauth2.googleapis.com/device/code` | `oauth2.googleapis.com/token` | `google.com/device` |
+| GitHub | `github.com/login/device/code` | `github.com/login/oauth/access_token` | `github.com/login/device` |
+
+*Note: Anthropic and OpenAI URLs are hypothetical - these providers would need to implement
+RFC 8628 device authorization. Currently, they only support browser-based OAuth.*
+
+### UI Flow
+
+**Step 1: User clicks "Login with [Provider]"**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Connect Claude Code                                             │
+│                                                                  │
+│  To connect your Anthropic account:                             │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  1. Click below to open Anthropic in a new tab             ││
+│  │  2. Sign in with your Anthropic account                    ││
+│  │  3. Enter the code shown here when prompted                ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  🔐  Open Anthropic →                                       ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Step 2: Show code, user enters at provider**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Connect Claude Code                                             │
+│                                                                  │
+│  Enter this code at Anthropic:                                  │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │                                                             ││
+│  │                    WDJB-MJPV                                ││
+│  │                                                             ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                         [Copy]                   │
+│                                                                  │
+│  A browser tab should have opened to console.anthropic.com     │
+│  Didn't open? Click here →                                      │
+│                                                                  │
+│  ───────────────────────────────────────────────────────────────│
+│                                                                  │
+│  ⏳ Waiting for you to authorize...                             │
+│     Code expires in 14:32                                       │
+│                                                                  │
+│  ┌──────────────┐                                               │
+│  │    Cancel    │                                               │
+│  └──────────────┘                                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Same flow for Codex:**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Connect OpenAI Codex                                            │
+│                                                                  │
+│  Enter this code at OpenAI:                                     │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │                                                             ││
+│  │                    XKCD-4815                                ││
+│  │                                                             ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                         [Copy]                   │
+│                                                                  │
+│  A browser tab should have opened to auth.openai.com           │
+│  Didn't open? Click here →                                      │
+│                                                                  │
+│  ───────────────────────────────────────────────────────────────│
+│                                                                  │
+│  ⏳ Waiting for you to authorize...                             │
+│     Code expires in 14:47                                       │
+│                                                                  │
+│  ┌──────────────┐                                               │
+│  │    Cancel    │                                               │
+│  └──────────────┘                                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Step 3: Success**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                  │
+│                    ✅ Connected!                                 │
+│                                                                  │
+│  Your Anthropic account is now linked.                         │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  Account: user@example.com                                  ││
+│  │  Plan: Claude Pro                                           ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │                     Continue  →                             ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Error States:**
+
+```
+Code Expired:
+┌─────────────────────────────────────────────────────────────────┐
+│  ⚠️ Code Expired                                                 │
+│                                                                  │
+│  The authorization code has expired. This happens if you        │
+│  don't complete the sign-in within 15 minutes.                  │
+│                                                                  │
+│  ┌───────────────────┐  ┌───────────────────────────────────┐   │
+│  │  Cancel           │  │  Get New Code                    │   │
+│  └───────────────────┘  └───────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+
+Access Denied:
+┌─────────────────────────────────────────────────────────────────┐
+│  ❌ Access Denied                                                │
+│                                                                  │
+│  You denied the authorization request at Anthropic.            │
+│                                                                  │
+│  ┌───────────────────┐  ┌───────────────────────────────────┐   │
+│  │  Cancel           │  │  Try Again                       │   │
+│  └───────────────────┘  └───────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### Device Flow Implementation
+
+```typescript
+// src/cloud/auth/device-flow.ts
+
+interface DeviceCodeResponse {
+  device_code: string;        // Secret - we use this for polling
+  user_code: string;          // Display to user: "WDJB-MJPV"
+  verification_uri: string;   // Where user goes: console.anthropic.com/device
+  verification_uri_complete?: string; // URL with code pre-filled (optional)
+  expires_in: number;         // Seconds until codes expire (typically 900)
+  interval: number;           // Min seconds between poll requests (typically 5)
+}
+
+interface DeviceFlowConfig {
+  provider: string;
+  deviceCodeUrl: string;
+  tokenUrl: string;
+  clientId: string;
+  scopes: string[];
+}
+
+const DEVICE_FLOW_CONFIGS: Record<string, DeviceFlowConfig> = {
+  anthropic: {
+    provider: 'anthropic',
+    deviceCodeUrl: 'https://api.anthropic.com/oauth/device/code',
+    tokenUrl: 'https://api.anthropic.com/oauth/token',
+    clientId: process.env.ANTHROPIC_CLIENT_ID!,
+    scopes: ['claude-code:execute', 'user:read']
+  },
+  openai: {
+    provider: 'openai',
+    deviceCodeUrl: 'https://auth.openai.com/device/code',
+    tokenUrl: 'https://auth.openai.com/oauth/token',
+    clientId: process.env.OPENAI_CLIENT_ID!,
+    scopes: ['openid', 'profile', 'email', 'codex:execute']
+  }
+};
+
+class DeviceFlowAuth {
+  private config: DeviceFlowConfig;
+
+  constructor(provider: string) {
+    this.config = DEVICE_FLOW_CONFIGS[provider];
+    if (!this.config) {
+      throw new Error(`No device flow config for provider: ${provider}`);
+    }
+  }
+
+  /**
+   * Step 1: Request device and user codes from provider
+   */
+  async requestCodes(): Promise<DeviceCodeResponse> {
+    const response = await fetch(this.config.deviceCodeUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded'
+      },
+      body: new URLSearchParams({
+        client_id: this.config.clientId,
+        scope: this.config.scopes.join(' ')
+      })
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Failed to get device code: ${error}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Step 2: Poll for tokens (called repeatedly until success/failure)
+   */
+  async pollForToken(deviceCode: string): Promise<PollResult> {
+    const response = await fetch(this.config.tokenUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded'
+      },
+      body: new URLSearchParams({
+        client_id: this.config.clientId,
+        device_code: deviceCode,
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code'
+      })
+    });
+
+    const data = await response.json();
+
+    // RFC 8628 error codes
+    if (data.error) {
+      switch (data.error) {
+        case 'authorization_pending':
+          // User hasn't completed authorization yet
+          return { status: 'pending' };
+
+        case 'slow_down':
+          // Polling too fast - increase interval
+          return {
+            status: 'slow_down',
+            retryAfter: data.interval || 10
+          };
+
+        case 'expired_token':
+          // Device code expired
+          return { status: 'expired' };
+
+        case 'access_denied':
+          // User denied authorization
+          return { status: 'denied' };
+
+        default:
+          return {
+            status: 'error',
+            error: data.error_description || data.error
+          };
+      }
+    }
+
+    // Success!
+    return {
+      status: 'success',
+      tokens: {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresIn: data.expires_in,
+        scope: data.scope
+      }
+    };
+  }
+}
+
+type PollResult =
+  | { status: 'pending' }
+  | { status: 'slow_down'; retryAfter: number }
+  | { status: 'expired' }
+  | { status: 'denied' }
+  | { status: 'error'; error: string }
+  | { status: 'success'; tokens: TokenSet };
+
+interface TokenSet {
+  accessToken: string;
+  refreshToken: string;
+  expiresIn: number;
+  scope: string;
+}
+```
+
+### Device Flow API Routes
+
+```typescript
+// src/cloud/api/device-flow.ts
+
+const router = Router();
+
+// Store for active device flows (use Redis in production)
+const activeFlows = new Map<string, ActiveFlow>();
+
+interface ActiveFlow {
+  userId: string;
+  provider: string;
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete?: string;
+  expiresAt: Date;
+  pollInterval: number;
+  status: 'pending' | 'success' | 'expired' | 'denied' | 'error';
+  tokens?: TokenSet;
+  error?: string;
+}
+
+/**
+ * POST /api/device-flow/:provider/start
+ * Initiates device flow, returns user code to display
+ */
+router.post('/:provider/start', async (req, res) => {
+  const { provider } = req.params;
+  const userId = req.session.userId;
+
+  try {
+    const auth = new DeviceFlowAuth(provider);
+    const codes = await auth.requestCodes();
+
+    const flowId = crypto.randomUUID();
+
+    activeFlows.set(flowId, {
+      userId,
+      provider,
+      deviceCode: codes.device_code,
+      userCode: codes.user_code,
+      verificationUri: codes.verification_uri,
+      verificationUriComplete: codes.verification_uri_complete,
+      expiresAt: new Date(Date.now() + codes.expires_in * 1000),
+      pollInterval: codes.interval,
+      status: 'pending'
+    });
+
+    // Start background polling
+    pollInBackground(flowId, auth);
+
+    res.json({
+      flowId,
+      userCode: codes.user_code,
+      verificationUri: codes.verification_uri,
+      verificationUriComplete: codes.verification_uri_complete,
+      expiresIn: codes.expires_in
+    });
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+/**
+ * GET /api/device-flow/:provider/status/:flowId
+ * Check status of device flow (client polls this)
+ */
+router.get('/:provider/status/:flowId', async (req, res) => {
+  const { flowId } = req.params;
+  const flow = activeFlows.get(flowId);
+
+  if (!flow) {
+    return res.status(404).json({ error: 'Flow not found' });
+  }
+
+  if (flow.userId !== req.session.userId) {
+    return res.status(403).json({ error: 'Unauthorized' });
+  }
+
+  const timeLeft = Math.max(0, Math.floor(
+    (flow.expiresAt.getTime() - Date.now()) / 1000
+  ));
+
+  res.json({
+    status: flow.status,
+    expiresIn: timeLeft,
+    error: flow.error
+  });
+});
+
+/**
+ * DELETE /api/device-flow/:provider/:flowId
+ * Cancel device flow
+ */
+router.delete('/:provider/:flowId', async (req, res) => {
+  const { flowId } = req.params;
+  const flow = activeFlows.get(flowId);
+
+  if (flow?.userId === req.session.userId) {
+    activeFlows.delete(flowId);
+  }
+
+  res.json({ success: true });
+});
+
+/**
+ * Background polling for device authorization
+ */
+async function pollInBackground(flowId: string, auth: DeviceFlowAuth) {
+  const flow = activeFlows.get(flowId);
+  if (!flow) return;
+
+  let interval = flow.pollInterval * 1000;
+
+  const poll = async () => {
+    const current = activeFlows.get(flowId);
+    if (!current || current.status !== 'pending') return;
+
+    // Check expiry
+    if (Date.now() > current.expiresAt.getTime()) {
+      current.status = 'expired';
+      return;
+    }
+
+    try {
+      const result = await auth.pollForToken(current.deviceCode);
+
+      switch (result.status) {
+        case 'pending':
+          setTimeout(poll, interval);
+          break;
+
+        case 'slow_down':
+          interval = result.retryAfter * 1000;
+          setTimeout(poll, interval);
+          break;
+
+        case 'success':
+          // Store tokens
+          await storeProviderTokens(current.userId, current.provider, result.tokens);
+          current.status = 'success';
+          current.tokens = result.tokens;
+          // Clean up after 60s
+          setTimeout(() => activeFlows.delete(flowId), 60000);
+          break;
+
+        case 'expired':
+        case 'denied':
+          current.status = result.status;
+          break;
+
+        case 'error':
+          current.status = 'error';
+          current.error = result.error;
+          break;
+      }
+    } catch (error) {
+      console.error('Poll error:', error);
+      // Retry with backoff
+      setTimeout(poll, interval * 2);
+    }
+  };
+
+  // Start after initial interval
+  setTimeout(poll, interval);
+}
+
+/**
+ * Store tokens after successful device flow
+ */
+async function storeProviderTokens(
+  userId: string,
+  provider: string,
+  tokens: TokenSet
+) {
+  // Get user info from provider
+  const userInfo = await fetchProviderUserInfo(provider, tokens.accessToken);
+
+  await credentialVault.store({
+    userId,
+    provider,
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken,
+    tokenExpiresAt: new Date(Date.now() + tokens.expiresIn * 1000),
+    scopes: tokens.scope.split(' '),
+    providerAccountId: userInfo.id,
+    providerAccountEmail: userInfo.email,
+    providerAccountName: userInfo.name,
+    connectedAt: new Date(),
+    isValid: true
+  });
+}
+```
+
+### Frontend Component
+
+```tsx
+// src/cloud/components/DeviceFlowAuth.tsx
+
+import { useState, useEffect, useCallback } from 'react';
+
+interface Props {
+  provider: 'anthropic' | 'openai';
+  providerName: string;  // "Anthropic" or "OpenAI"
+  onSuccess: () => void;
+  onCancel: () => void;
+}
+
+type State =
+  | { step: 'ready' }
+  | { step: 'loading' }
+  | { step: 'showing_code'; flowId: string; userCode: string;
+      verificationUri: string; expiresAt: Date }
+  | { step: 'success' }
+  | { step: 'error'; message: string; canRetry: boolean };
+
+export function DeviceFlowAuth({ provider, providerName, onSuccess, onCancel }: Props) {
+  const [state, setState] = useState<State>({ step: 'ready' });
+  const [timeLeft, setTimeLeft] = useState(0);
+
+  // Start the device flow
+  const startFlow = useCallback(async () => {
+    setState({ step: 'loading' });
+
+    try {
+      const res = await fetch(`/api/device-flow/${provider}/start`, {
+        method: 'POST',
+        credentials: 'include'
+      });
+      const data = await res.json();
+
+      if (!res.ok) throw new Error(data.error);
+
+      setState({
+        step: 'showing_code',
+        flowId: data.flowId,
+        userCode: data.userCode,
+        verificationUri: data.verificationUri,
+        expiresAt: new Date(Date.now() + data.expiresIn * 1000)
+      });
+
+      // Open provider auth page
+      window.open(
+        data.verificationUriComplete || data.verificationUri,
+        '_blank',
+        'noopener'
+      );
+    } catch (error) {
+      setState({
+        step: 'error',
+        message: error.message,
+        canRetry: true
+      });
+    }
+  }, [provider]);
+
+  // Poll for status
+  useEffect(() => {
+    if (state.step !== 'showing_code') return;
+
+    const checkStatus = async () => {
+      try {
+        const res = await fetch(
+          `/api/device-flow/${provider}/status/${state.flowId}`,
+          { credentials: 'include' }
+        );
+        const data = await res.json();
+
+        switch (data.status) {
+          case 'success':
+            setState({ step: 'success' });
+            setTimeout(onSuccess, 1500);
+            break;
+          case 'expired':
+            setState({
+              step: 'error',
+              message: 'Code expired. Please try again.',
+              canRetry: true
+            });
+            break;
+          case 'denied':
+            setState({
+              step: 'error',
+              message: 'Authorization was denied.',
+              canRetry: true
+            });
+            break;
+          case 'error':
+            setState({
+              step: 'error',
+              message: data.error || 'An error occurred.',
+              canRetry: true
+            });
+            break;
+          // 'pending' - keep polling
+        }
+      } catch (error) {
+        console.error('Status check failed:', error);
+      }
+    };
+
+    const interval = setInterval(checkStatus, 2000);
+    return () => clearInterval(interval);
+  }, [state, provider, onSuccess]);
+
+  // Countdown timer
+  useEffect(() => {
+    if (state.step !== 'showing_code') return;
+
+    const tick = () => {
+      const remaining = Math.floor(
+        (state.expiresAt.getTime() - Date.now()) / 1000
+      );
+      setTimeLeft(Math.max(0, remaining));
+    };
+
+    tick();
+    const interval = setInterval(tick, 1000);
+    return () => clearInterval(interval);
+  }, [state]);
+
+  const formatTime = (s: number) =>
+    `${Math.floor(s / 60)}:${(s % 60).toString().padStart(2, '0')}`;
+
+  const copyCode = () => {
+    if (state.step === 'showing_code') {
+      navigator.clipboard.writeText(state.userCode);
+    }
+  };
+
+  // Render
+  switch (state.step) {
+    case 'ready':
+      return (
+        <div className="device-flow">
+          <h2>Connect {providerName}</h2>
+          <p>
+            Click below to sign in with your {providerName} account.
+            You'll enter a code to link your account.
+          </p>
+          <div className="actions">
+            <button onClick={startFlow} className="primary">
+              Open {providerName} →
+            </button>
+            <button onClick={onCancel} className="secondary">
+              Cancel
+            </button>
+          </div>
+        </div>
+      );
+
+    case 'loading':
+      return (
+        <div className="device-flow loading">
+          <div className="spinner" />
+          <p>Preparing authorization...</p>
+        </div>
+      );
+
+    case 'showing_code':
+      return (
+        <div className="device-flow">
+          <h2>Enter this code at {providerName}</h2>
+
+          <div className="code-box">
+            <code className="user-code">{state.userCode}</code>
+            <button onClick={copyCode} className="copy-btn">
+              Copy
+            </button>
+          </div>
+
+          <p className="hint">
+            A browser tab opened to{' '}
+            <a href={state.verificationUri} target="_blank" rel="noopener">
+              {new URL(state.verificationUri).hostname}
+            </a>
+          </p>
+
+          <div className="status">
+            <span className="spinner small" />
+            <span>Waiting for authorization...</span>
+          </div>
+
+          <div className="timer">
+            Code expires in {formatTime(timeLeft)}
+          </div>
+
+          <button onClick={onCancel} className="secondary">
+            Cancel
+          </button>
+        </div>
+      );
+
+    case 'success':
+      return (
+        <div className="device-flow success">
+          <div className="icon">✅</div>
+          <h2>Connected!</h2>
+          <p>Your {providerName} account is now linked.</p>
+        </div>
+      );
+
+    case 'error':
+      return (
+        <div className="device-flow error">
+          <div className="icon">❌</div>
+          <h2>Connection Failed</h2>
+          <p>{state.message}</p>
+          <div className="actions">
+            {state.canRetry && (
+              <button onClick={startFlow} className="primary">
+                Try Again
+              </button>
+            )}
+            <button onClick={onCancel} className="secondary">
+              Cancel
+            </button>
+          </div>
+        </div>
+      );
+  }
+}
+```
+
+---
+
+#### Credential Import (Alternative for Claude)
+
+For users who prefer to authenticate locally first:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Connect Claude Code                                             │
+│                                                                  │
+│  Choose how to connect:                                         │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  🔐 Login with Anthropic                                    ││
+│  │  Authenticate in browser (recommended)                      ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │  📁 Import from Local Claude                                ││
+│  │  Already have Claude Code installed? Import credentials     ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Import flow:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Import Claude Credentials                                       │
+│                                                                  │
+│  Run this command on your local machine:                        │
+│                                                                  │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │ npx agent-relay-cloud export-credentials                    ││
+│  └─────────────────────────────────────────────────────────────┘│
+│  [Copy]                                                         │
+│                                                                  │
+│  This will:                                                     │
+│  • Read your Claude credentials from ~/.claude/                 │
+│  • Encrypt them with a one-time code                           │
+│  • Upload securely to Agent Relay Cloud                        │
+│                                                                  │
+│  Your credentials never leave your machine unencrypted.        │
+│                                                                  │
+│  ⏳ Waiting for import...                                       │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Step 4: Configure Your First Team (Optional)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Create Your First Agent Team                                    │
+│                                                                  │
+│  Teams are groups of AI agents that work together on tasks.     │
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │  🚀 Quick Start Templates                                │   │
+│  ├──────────────────────────────────────────────────────────┤   │
+│  │                                                          │   │
+│  │  ┌────────────────────────────────────────────────────┐ │   │
+│  │  │ 👥 Code Review Team                                │ │   │
+│  │  │ Architect + Reviewer + Security Auditor            │ │   │
+│  │  │ Auto-reviews PRs and suggests improvements         │ │   │
+│  │  └────────────────────────────────────────────────────┘ │   │
+│  │                                                          │   │
+│  │  ┌────────────────────────────────────────────────────┐ │   │
+│  │  │ 🛠️  Feature Development Team                       │ │   │
+│  │  │ Lead + Frontend + Backend + Tester                 │ │   │
+│  │  │ Coordinates multi-agent feature builds             │ │   │
+│  │  └────────────────────────────────────────────────────┘ │   │
+│  │                                                          │   │
+│  │  ┌────────────────────────────────────────────────────┐ │   │
+│  │  │ 📝 Custom Team                                     │ │   │
+│  │  │ Configure your own agent composition               │ │   │
+│  │  └────────────────────────────────────────────────────┘ │   │
+│  │                                                          │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                                                                  │
+│  ┌──────────────┐  ┌──────────────────────────────────────────┐ │
+│  │ Skip for now │  │  Select template  →                     │ │
+│  └──────────────┘  └──────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Step 5: Ready to Go!
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  🎉 You're all set!                                              │
+│                                                                  │
+│  Your Agent Relay Cloud workspace is ready:                     │
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │  📂 Repositories          2 connected                    │   │
+│  │  🤖 Agent Providers       Claude, Codex                  │   │
+│  │  👥 Teams                 Code Review Team               │   │
+│  │  🌐 Dashboard             relay.yourdomain.cloud         │   │
+│  └──────────────────────────────────────────────────────────┘   │
+│                                                                  │
+│  What's next?                                                   │
+│                                                                  │
+│  • Open a PR to trigger automatic code review                   │
+│  • Use @agent-relay in PR comments to chat with agents          │
+│  • Visit your dashboard to monitor agent activity               │
+│                                                                  │
+│  ┌──────────────────────────────────────────────────────────┐   │
+│  │  Open Dashboard  →                                       │   │
+│  └──────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Technical Implementation
+
+### Provider Credentials Storage
+
+```typescript
+// src/cloud/providers/types.ts
+
+interface ProviderCredential {
+  id: string;
+  userId: string;
+  provider: ProviderType;
+
+  // OAuth tokens (encrypted at rest)
+  accessToken: string;
+  refreshToken: string;
+  tokenExpiresAt: Date;
+  scopes: string[];
+
+  // Account info from provider
+  providerAccountId: string;    // Provider's user ID
+  providerAccountEmail: string; // For display: "user@example.com"
+  providerAccountName?: string; // Display name if available
+
+  // Metadata
+  connectedAt: Date;
+  lastUsedAt?: Date;
+  lastRefreshedAt?: Date;
+  isValid: boolean;
+}
+
+type ProviderType =
+  | 'anthropic'    // Claude Code
+  | 'openai'       // Codex, ChatGPT
+  | 'google'       // Gemini
+  | 'github'       // Copilot (auto-connected via signup)
+  | 'microsoft'    // Azure OpenAI
+  | 'self-hosted'; // Ollama, LM Studio (no auth needed)
+```
+
+### Provider Registry
+
+```typescript
+// src/cloud/providers/registry.ts
+
+interface OAuthConfig {
+  authorizationUrl: string;
+  tokenUrl: string;
+  scopes: string[];
+  userInfoUrl?: string;  // To fetch account email/name after auth
+}
+
+interface ProviderConfig {
+  id: ProviderType;
+  name: string;
+  displayName: string;  // "Login with {displayName}"
+  description: string;
+  cliCommand: string;
+  cliArgs?: string[];
+  oauthConfig: OAuthConfig;
+  icon: string;
+  color: string;  // Brand color for button
+}
+
+const PROVIDER_REGISTRY: ProviderConfig[] = [
+  {
+    id: 'anthropic',
+    name: 'Anthropic',
+    displayName: 'Anthropic',
+    description: 'Claude Code - recommended for code tasks',
+    cliCommand: 'claude',
+    cliArgs: ['--dangerously-skip-permissions'],
+    oauthConfig: {
+      authorizationUrl: 'https://console.anthropic.com/oauth/authorize',
+      tokenUrl: 'https://api.anthropic.com/oauth/token',
+      scopes: ['claude-code:execute', 'user:read'],
+      userInfoUrl: 'https://api.anthropic.com/v1/user'
+    },
+    icon: 'anthropic-logo.svg',
+    color: '#D97757'
+  },
+  {
+    id: 'openai',
+    name: 'OpenAI',
+    displayName: 'OpenAI',
+    description: 'Codex and ChatGPT models',
+    cliCommand: 'codex',
+    cliArgs: ['--dangerously-bypass-approvals-and-sandbox'],
+    oauthConfig: {
+      authorizationUrl: 'https://auth.openai.com/authorize',
+      tokenUrl: 'https://auth.openai.com/oauth/token',
+      scopes: ['openid', 'profile', 'email', 'model.read', 'model.request'],
+      userInfoUrl: 'https://api.openai.com/v1/user'
+    },
+    icon: 'openai-logo.svg',
+    color: '#10A37F'
+  },
+  {
+    id: 'google',
+    name: 'Google',
+    displayName: 'Google',
+    description: 'Gemini - multi-modal capabilities',
+    cliCommand: 'gemini',
+    oauthConfig: {
+      authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+      tokenUrl: 'https://oauth2.googleapis.com/token',
+      scopes: [
+        'openid',
+        'email',
+        'profile',
+        'https://www.googleapis.com/auth/generative-language'
+      ],
+      userInfoUrl: 'https://www.googleapis.com/oauth2/v2/userinfo'
+    },
+    icon: 'google-logo.svg',
+    color: '#4285F4'
+  },
+  {
+    id: 'github',
+    name: 'GitHub',
+    displayName: 'GitHub',
+    description: 'Copilot - auto-connected via signup',
+    cliCommand: 'gh-copilot',
+    oauthConfig: {
+      // Uses same OAuth from signup - just needs Copilot scope
+      authorizationUrl: 'https://github.com/login/oauth/authorize',
+      tokenUrl: 'https://github.com/login/oauth/access_token',
+      scopes: ['copilot', 'read:user', 'user:email'],
+      userInfoUrl: 'https://api.github.com/user'
+    },
+    icon: 'github-logo.svg',
+    color: '#24292F'
+  },
+  {
+    id: 'microsoft',
+    name: 'Microsoft',
+    displayName: 'Microsoft',
+    description: 'Azure OpenAI - enterprise deployments',
+    cliCommand: 'azure-openai',
+    oauthConfig: {
+      authorizationUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+      tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+      scopes: [
+        'openid',
+        'profile',
+        'email',
+        'https://cognitiveservices.azure.com/.default'
+      ],
+      userInfoUrl: 'https://graph.microsoft.com/v1.0/me'
+    },
+    icon: 'microsoft-logo.svg',
+    color: '#00A4EF'
+  }
+];
+
+// Self-hosted providers don't need OAuth
+interface SelfHostedProvider {
+  id: 'self-hosted';
+  name: string;
+  endpoint: string;  // e.g., "http://localhost:11434" for Ollama
+  cliCommand: string;
+}
+```
+
+### Spawner Integration
+
+```typescript
+// src/cloud/spawner-cloud.ts
+
+class CloudAgentSpawner extends AgentSpawner {
+  private credentialVault: CredentialVault;
+  private tokenRefresher: TokenRefresher;
+
+  async spawn(request: CloudSpawnRequest): Promise<SpawnedAgent> {
+    const { userId, provider, agentName, task } = request;
+
+    // Get credentials for this provider
+    const credential = await this.credentialVault.get(userId, provider);
+    if (!credential) {
+      throw new ProviderNotConnectedError(provider);
+    }
+
+    // Refresh token if expired or expiring soon (within 5 min)
+    const validCredential = await this.ensureValidToken(credential);
+
+    // Build environment with OAuth token
+    const env = this.buildProviderEnv(validCredential);
+
+    // Get provider config
+    const providerConfig = PROVIDER_REGISTRY.find(p => p.id === provider);
+
+    // Spawn agent with credentials injected
+    return super.spawn({
+      name: agentName,
+      cli: providerConfig.cliCommand,
+      args: providerConfig.cliArgs,
+      env,
+      task
+    });
+  }
+
+  private async ensureValidToken(credential: ProviderCredential): Promise<ProviderCredential> {
+    const expiresIn = credential.tokenExpiresAt.getTime() - Date.now();
+    const FIVE_MINUTES = 5 * 60 * 1000;
+
+    if (expiresIn < FIVE_MINUTES) {
+      // Refresh the token
+      const provider = PROVIDER_REGISTRY.find(p => p.id === credential.provider);
+      const newTokens = await this.tokenRefresher.refresh(
+        provider.oauthConfig,
+        credential.refreshToken
+      );
+
+      // Update stored credential
+      const updated = await this.credentialVault.update(credential.id, {
+        accessToken: newTokens.accessToken,
+        refreshToken: newTokens.refreshToken ?? credential.refreshToken,
+        tokenExpiresAt: newTokens.expiresAt,
+        lastRefreshedAt: new Date()
+      });
+
+      return updated;
+    }
+
+    return credential;
+  }
+
+  private buildProviderEnv(credential: ProviderCredential): Record<string, string> {
+    // Each provider expects OAuth token in different env vars
+    const envMapping: Record<ProviderType, string> = {
+      'anthropic': 'ANTHROPIC_AUTH_TOKEN',
+      'openai': 'OPENAI_AUTH_TOKEN',
+      'google': 'GOOGLE_AUTH_TOKEN',
+      'github': 'GITHUB_TOKEN',
+      'microsoft': 'AZURE_AUTH_TOKEN',
+      'self-hosted': '' // No auth needed
+    };
+
+    const envVar = envMapping[credential.provider];
+    if (!envVar) return {};
+
+    return {
+      [envVar]: credential.accessToken,
+      // Some CLIs also want the account info
+      'PROVIDER_ACCOUNT_EMAIL': credential.providerAccountEmail
+    };
+  }
+}
+
+class ProviderNotConnectedError extends Error {
+  constructor(provider: ProviderType) {
+    super(`Provider "${provider}" is not connected. Please connect it in Settings.`);
+    this.name = 'ProviderNotConnectedError';
+  }
+}
+```
+
+### Onboarding API
+
+```typescript
+// src/cloud/api/onboarding.ts
+
+const onboardingRouter = Router();
+
+// Step 1: GitHub OAuth callback (primary signup/login)
+onboardingRouter.get('/auth/github/callback', async (req, res) => {
+  const { code } = req.query;
+  const tokens = await exchangeGitHubCode(code);
+  const user = await createOrUpdateUser(tokens);
+
+  // Store GitHub credential (also gives us Copilot access)
+  await credentialVault.store({
+    userId: user.id,
+    provider: 'github',
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken,
+    tokenExpiresAt: tokens.expiresAt,
+    scopes: tokens.scopes,
+    providerAccountId: tokens.user.id,
+    providerAccountEmail: tokens.user.email,
+    providerAccountName: tokens.user.name,
+    connectedAt: new Date(),
+    isValid: true
+  });
+
+  // Set session and redirect to repo selection
+  req.session.userId = user.id;
+  res.redirect('/onboarding/repositories');
+});
+
+// Step 2: Get user's repositories
+onboardingRouter.get('/repositories', async (req, res) => {
+  const repos = await github.listUserRepos(req.session.accessToken);
+  res.json({ repos });
+});
+
+// Step 2: Connect selected repositories
+onboardingRouter.post('/repositories', async (req, res) => {
+  const { repoIds } = req.body;
+  await Promise.all(repoIds.map(id =>
+    connectRepository(req.session.userId, id)
+  ));
+  res.json({ success: true });
+});
+
+// Step 3: List available providers with connection status
+onboardingRouter.get('/providers', async (req, res) => {
+  const connected = await getConnectedProviders(req.session.userId);
+
+  // Map registry with connection status
+  const providers = PROVIDER_REGISTRY.map(p => ({
+    ...p,
+    isConnected: connected.some(c => c.provider === p.id),
+    connectedAs: connected.find(c => c.provider === p.id)?.providerAccountEmail
+  }));
+
+  res.json({ providers });
+});
+
+// Step 3: Initiate OAuth login for a provider
+onboardingRouter.get('/providers/:provider/login', async (req, res) => {
+  const { provider } = req.params;
+  const config = PROVIDER_REGISTRY.find(p => p.id === provider);
+
+  if (!config) {
+    return res.status(404).json({ error: 'Unknown provider' });
+  }
+
+  // Generate state token for CSRF protection
+  const state = await generateOAuthState({
+    userId: req.session.userId,
+    provider,
+    returnTo: req.query.returnTo || '/onboarding/providers'
+  });
+
+  // Build OAuth authorization URL
+  const authUrl = new URL(config.oauthConfig.authorizationUrl);
+  authUrl.searchParams.set('client_id', getClientId(provider));
+  authUrl.searchParams.set('redirect_uri', `${BASE_URL}/providers/${provider}/callback`);
+  authUrl.searchParams.set('scope', config.oauthConfig.scopes.join(' '));
+  authUrl.searchParams.set('state', state);
+  authUrl.searchParams.set('response_type', 'code');
+
+  res.redirect(authUrl.toString());
+});
+
+// Step 3: OAuth callback after user authorizes
+onboardingRouter.get('/providers/:provider/callback', async (req, res) => {
+  const { code, state, error } = req.query;
+
+  if (error) {
+    return res.redirect(`/onboarding/providers?error=${error}`);
+  }
+
+  // Verify state token
+  const stateData = await verifyOAuthState(state);
+  if (!stateData) {
+    return res.status(400).json({ error: 'Invalid state' });
+  }
+
+  const { userId, provider, returnTo } = stateData;
+  const config = PROVIDER_REGISTRY.find(p => p.id === provider);
+
+  // Exchange code for tokens
+  const tokens = await exchangeOAuthCode({
+    tokenUrl: config.oauthConfig.tokenUrl,
+    code,
+    clientId: getClientId(provider),
+    clientSecret: getClientSecret(provider),
+    redirectUri: `${BASE_URL}/providers/${provider}/callback`
+  });
+
+  // Fetch user info from provider
+  const userInfo = await fetchProviderUserInfo(
+    config.oauthConfig.userInfoUrl,
+    tokens.accessToken
+  );
+
+  // Store credential
+  await credentialVault.store({
+    userId,
+    provider,
+    accessToken: tokens.accessToken,
+    refreshToken: tokens.refreshToken,
+    tokenExpiresAt: new Date(Date.now() + tokens.expiresIn * 1000),
+    scopes: tokens.scope.split(' '),
+    providerAccountId: userInfo.id,
+    providerAccountEmail: userInfo.email,
+    providerAccountName: userInfo.name,
+    connectedAt: new Date(),
+    isValid: true
+  });
+
+  res.redirect(`${returnTo}?connected=${provider}`);
+});
+
+// Step 3: Disconnect a provider
+onboardingRouter.delete('/providers/:provider', async (req, res) => {
+  const { provider } = req.params;
+
+  await credentialVault.delete(req.session.userId, provider);
+
+  res.json({ success: true });
+});
+
+// Step 4: Create team from template
+onboardingRouter.post('/teams/from-template', async (req, res) => {
+  const { templateId, repoIds, defaultProvider } = req.body;
+  const template = TEAM_TEMPLATES[templateId];
+
+  // Verify user has the default provider connected
+  const hasProvider = await credentialVault.exists(
+    req.session.userId,
+    defaultProvider || 'anthropic'
+  );
+
+  if (!hasProvider) {
+    return res.status(400).json({
+      error: 'Provider not connected',
+      message: `Please connect ${defaultProvider || 'Anthropic'} first`
+    });
+  }
+
+  const team = await createTeam({
+    userId: req.session.userId,
+    name: template.name,
+    agents: template.agents.map(a => ({
+      ...a,
+      provider: defaultProvider || 'anthropic'
+    })),
+    repoIds
+  });
+
+  res.json({ team });
+});
+
+// Complete onboarding
+onboardingRouter.post('/complete', async (req, res) => {
+  await markOnboardingComplete(req.session.userId);
+
+  // Provision workspace
+  const workspace = await provisionWorkspace(req.session.userId);
+
+  res.json({
+    dashboardUrl: workspace.dashboardUrl,
+    webhookUrl: workspace.webhookUrl
+  });
+});
+```
+
+---
+
+## Security Considerations
+
+### OAuth Token Security
+
+1. **Encryption at rest**: All tokens encrypted with AES-256-GCM
+2. **Key derivation**: Per-user encryption keys derived from master key + user ID
+3. **No plaintext logging**: Tokens never logged, even in debug mode
+4. **Short-lived access tokens**: Rely on refresh tokens for long sessions
+
+### Token Lifecycle Management
+
+1. **Automatic refresh**: Tokens refreshed 5 minutes before expiry
+2. **Refresh token rotation**: Use rotating refresh tokens where supported
+3. **Revocation detection**: Check token validity on spawn, prompt re-auth if revoked
+4. **Graceful degradation**: Queue tasks if token refresh fails temporarily
+
+### Scope Management
+
+1. **Minimum scopes**: Request only scopes needed for agent execution
+2. **Scope display**: Show users exactly what permissions we request
+3. **No scope creep**: Never silently request additional scopes
+
+### Access Control
+
+1. **User isolation**: Credentials tied to user ID, never shared
+2. **Team permissions**: Team admins can enable provider access for team members
+3. **Audit logging**: All credential access and agent spawns logged
+4. **Rate limiting**: Provider usage rate-limited per user/team
+
+---
+
+## Future Enhancements
+
+### 1. Credential Sharing for Teams
+
+Allow team admins to share provider credentials with team members:
+
+```typescript
+interface SharedCredential {
+  credentialId: string;
+  teamId: string;
+  sharedBy: string;
+  permissions: 'read' | 'use';  // 'use' allows spawning agents
+}
+```
+
+### 2. Usage Tracking & Billing
+
+Track provider usage per user/team for billing:
+
+```typescript
+interface UsageRecord {
+  userId: string;
+  teamId?: string;
+  provider: ProviderType;
+  agentName: string;
+  tokensUsed: number;
+  duration: number;
+  timestamp: Date;
+}
+```
+
+### 3. Provider Health Monitoring
+
+Monitor provider availability and quota:
+
+```typescript
+interface ProviderHealth {
+  provider: ProviderType;
+  status: 'healthy' | 'degraded' | 'down';
+  quotaRemaining?: number;
+  lastChecked: Date;
+}
+```
+
+### 4. Bring Your Own Cloud
+
+Let users connect their own cloud accounts for compute:
+
+- AWS credentials for EC2 instances
+- GCP credentials for Cloud Run
+- Azure credentials for Container Instances
+
+---
+
+## Summary
+
+The onboarding flow prioritizes:
+
+1. **Low friction**: GitHub OAuth gets users started immediately
+2. **Consistent UX**: All providers use "Login with X" - no API keys to manage
+3. **Security**: OAuth tokens with automatic refresh, encrypted at rest
+4. **Account linking**: Users log in with their existing provider accounts
+5. **Progressive disclosure**: Optional team setup, can skip and add later
+6. **Graceful recovery**: Re-auth prompts when tokens expire or get revoked
+
+Users can connect all their AI providers during onboarding with simple login buttons, or add them later from Settings. GitHub Copilot is auto-connected via the initial signup flow.