feat: Add Orchestrator Client Mode for Remote Access via Central Hub #319

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

liamhelmer wants to merge 43 commits into siteboon:main from Epiphytic:feat/orchestrator-client-mode

.env.example

-Original file line number
+Diff line change
@@ Expand Up / @@ -39,3 +39,57 @@ VITE_CONTEXT_WINDOW=160000 @@
     CONTEXT_WINDOW=160000
     # VITE_IS_PLATFORM=false
+    # =============================================================================
+    # ORCHESTRATOR CONFIGURATION
+    # =============================================================================
+    # Orchestrator mode determines how this instance operates:
+    #   standalone - Runs independently (default)
+    #   client     - Connects to a central orchestrator server
+    ORCHESTRATOR_MODE=standalone
+    # Orchestrator WebSocket URL (required when ORCHESTRATOR_MODE=client)
+    # This is the base URL of the orchestrator server - the token is automatically appended
+    # ORCHESTRATOR_URL=wss://orchestrator.example.com/ws/connect
+    # Orchestrator authentication token (required when ORCHESTRATOR_MODE=client)
+    # Generate this token from the orchestrator dashboard
+    # The token is automatically appended to the URL as a query parameter
+    # ORCHESTRATOR_TOKEN=
+    # Optional: Custom client ID for this instance
+    # If not set, defaults to hostname-pid
+    # ORCHESTRATOR_CLIENT_ID=
+    # Optional: Reconnection interval in milliseconds (default: 5000)
+    # ORCHESTRATOR_RECONNECT_INTERVAL=5000
+    # Optional: Heartbeat interval in milliseconds (default: 30000)
+    # ORCHESTRATOR_HEARTBEAT_INTERVAL=30000
+    # =============================================================================
+    # ORCHESTRATOR PASS-THROUGH AUTHENTICATION
+    # =============================================================================
+    # When in client mode, you can configure which GitHub users are allowed to
+    # access this instance via the orchestrator. The orchestrator passes the user's
+    # GitHub OAuth token, and claudecodeui validates it against these rules.
+    #
+    # Set ONE OR MORE of the following to enable pass-through auth:
+    # Allow users from a specific GitHub organization
+    # ORCHESTRATOR_GITHUB_ORG=your-org-name
+    # Allow users from a specific GitHub team (format: org/team-slug)
+    # ORCHESTRATOR_GITHUB_TEAM=your-org/your-team
+    # Allow specific GitHub usernames (comma-separated for multiple users)
+    # ORCHESTRATOR_GITHUB_USERS=username1,username2,username3
+    # Authentication priority (if multiple are set):
+    # 1. Specific users (ORCHESTRATOR_GITHUB_USERS) - checked first
+    # 2. Team membership (ORCHESTRATOR_GITHUB_TEAM) - checked second
+    # 3. Org membership (ORCHESTRATOR_GITHUB_ORG) - checked last
+    #
+    # If NONE of these are set, pass-through auth is disabled and requests
+    # from the orchestrator will be processed without user validation.

.gitignore

-Original file line number
+Diff line change
@@ Expand Up / @@ -130,3 +130,4 @@ dev-debug.log @@
     # Task files
     tasks.json
     tasks/
+    .fork-join/

PR_DESCRIPTION.md

-Original file line number
+Diff line change
@@ -0,0 +1,178 @@
+    # feat: Add Orchestrator Client Mode for Remote Access via Central Hub
+    ## Summary
+    This PR adds orchestrator client mode to claudecodeui, enabling instances to connect to a central orchestrator server for remote access and management. Users can now access their Claude Code UI instances from anywhere through a unified web interface, with automatic authentication pass-through and real-time status reporting.
+    ## Motivation
+    When running Claude Code UI on multiple machines (development servers, remote workstations, etc.), users need a way to:
+    - Access all instances from a single dashboard
+    - Authenticate once at the orchestrator level
+    - View real-time status (idle/active/busy) of each instance
+    - Use the full web interface through a reverse proxy
+    ## Key Features
+    - **WebSocket-based orchestrator connection** with automatic reconnection and heartbeats
+    - **HTTP proxy support** allowing full UI access through the orchestrator
+    - **Auto-authentication pass-through** from orchestrator's GitHub OAuth to local instances
+    - **Real-time status tracking** (idle → active → busy) reported to orchestrator
+    - **PWA support through proxy** with service worker URL normalization
+    - **Graceful degradation** - runs standalone if orchestrator is unavailable
+    ## Architecture
+    ```
+    ┌─────────────────┐     ┌──────────────────────────────────────────────┐
+    │  claudecodeui   │────▶│         Orchestrator Server                  │
+    │   instance 1    │     │  (Cloudflare Workers + Durable Objects)      │
+    └─────────────────┘     │                                              │
+                            │  - WebSocket hub per user                    │
+    ┌─────────────────┐     │  - HTTP proxy to instances                   │
+    │  claudecodeui   │────▶│  - GitHub OAuth authentication               │
+    │   instance 2    │     │  - Real-time status dashboard                │
+    └─────────────────┘     │                                              │
+                            └──────────────────────────────────────────────┘
+         ┌──────────┐                          │
+         │ Browser  │◀─────────────────────────┘
+         │ (User)   │    (Single entry point for all instances)
+         └──────────┘
+    ```
+    ## Files Changed
+    ### New Files: `server/orchestrator/`
+    | File                | Purpose                                                                                                                                      |
+    | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+    | `index.js`          | Main orchestrator module - exports all components, provides `initializeOrchestrator()` factory function                                      |
+    | `client.js`         | `OrchestratorClient` class - WebSocket client with auto-reconnect, heartbeats, HTTP proxy handling, URL rewriting                            |
+    | `protocol.js`       | Message protocol definitions for claudecodeui ↔ orchestrator communication (register, status_update, ping/pong, http_proxy_request/response) |
+    | `github-auth.js`    | GitHub OAuth validation for pass-through authentication (org/team/user restrictions)                                                         |
+    | `status-tracker.js` | Tracks Claude session status (idle/active/busy) and reports changes to orchestrator                                                          |
+    | `proxy.js`          | WebSocket proxy utilities for handling user requests routed through orchestrator                                                             |
+    ### Modified Files
+    | File                        | Changes                                                                                                                 |
+    | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+    | `server/cli.js`             | Added orchestrator initialization on server startup; environment variable handling for orchestrator config              |
+    | `server/middleware/auth.js` | Added debug logging for JWT verification; supports orchestrator-generated tokens                                        |
+    | `server/database/db.js`     | Added `getOrCreateUser()` for auto-creating users from orchestrator OAuth; bcrypt import for password handling          |
+    | `public/sw.js`              | Added `proxyBase` query parameter support for PWA through proxy; URL normalization for cache keys                       |
+    | `src/App.jsx`               | Added dynamic React Router `basename` detection for proxy access; ensures routing works at `/clients/{id}/proxy/` paths |
+    | `.env.example`              | Added orchestrator configuration documentation (ORCHESTRATOR_MODE, URL, TOKEN, etc.)                                    |
+    ## Configuration
+    ### Environment Variables
+    ```bash
+    # Orchestrator mode: 'standalone' (default) or 'client'
+    ORCHESTRATOR_MODE=client
+    # Orchestrator WebSocket URL
+    ORCHESTRATOR_URL=wss://orchestrator.example.com/ws/connect
+    # Authentication token from orchestrator dashboard
+    ORCHESTRATOR_TOKEN=your-token-here
+    # Optional: Custom client ID (defaults to hostname-pid)
+    ORCHESTRATOR_CLIENT_ID=my-dev-machine
+    # Optional: Reconnection/heartbeat intervals (ms)
+    ORCHESTRATOR_RECONNECT_INTERVAL=5000
+    ORCHESTRATOR_HEARTBEAT_INTERVAL=30000
+    # Pass-through auth: restrict which GitHub users can access
+    ORCHESTRATOR_GITHUB_ORG=your-org
+    ORCHESTRATOR_GITHUB_TEAM=your-org/your-team
+    ORCHESTRATOR_GITHUB_USERS=user1,user2
+    ```
+    ## Technical Details
+    ### HTTP Proxy URL Rewriting
+    When requests come through the orchestrator proxy (`/clients/{id}/proxy/*`), the client performs URL rewriting to ensure the React app works correctly:
+. **HTML rewriting** (`rewriteHtmlUrls`):
+       - Rewrites `src="/..."`, `href="/..."`, `action="/..."` attributes
+       - Injects `fetch()` patch script to redirect API calls through proxy
+       - Injects auto-authentication script with orchestrator-generated JWT
+       - Adds service worker registration with `proxyBase` query parameter
+. **JavaScript rewriting** (`rewriteJsUrls`):
+       - Rewrites string literals for known URL prefixes (api, assets, auth, ws, etc.)
+       - Preserves regex patterns to avoid breaking code
+. **Service Worker** (`sw.js`):
+       - Accepts `proxyBase` parameter to normalize cache keys
+       - Handles both direct and proxied access transparently
+    ### Auto-Authentication Flow
+. User authenticates with orchestrator via GitHub OAuth
+. Orchestrator proxies HTTP request to claudecodeui with `X-Orchestrator-User-Id` and `X-Orchestrator-Username` headers
+. `OrchestratorClient.handleHttpProxyRequest()` calls `getOrCreateOrchestratorToken()`
+. Token is generated for the orchestrator user (creating user in DB if needed)
+. HTML response includes injected `<script>` that stores token in localStorage
+. React app initializes with valid authentication
+    ### Status Tracking
+    The `StatusTracker` monitors:
+    - Active WebSocket connections (browser tabs)
+    - Busy sessions (Claude generating responses)
+    Status values:
+    - `idle`: No active connections
+    - `active`: Browser connected, not generating
+    - `busy`: Claude is generating a response
+    ### Message Protocol
+    **Outbound (claudecodeui → Orchestrator):**
+    - `register`: Initial registration with metadata
+    - `status_update`: Status changes (idle/active/busy)
+    - `ping`: Heartbeat
+    - `http_proxy_response`: Response to proxied HTTP request
+    **Inbound (Orchestrator → claudecodeui):**
+    - `registered`: Registration confirmation
+    - `pong`: Heartbeat response
+    - `command`: Commands (disconnect, refresh_status)
+    - `http_proxy_request`: Proxied HTTP request
+    ## Testing
+. **Standalone mode** (default): No changes to existing behavior
+. **Client mode**:
+       - Set `ORCHESTRATOR_MODE=client` with URL and token
+       - Verify WebSocket connection to orchestrator
+       - Access UI through orchestrator proxy URL
+       - Verify auto-authentication works
+       - Verify status updates appear in orchestrator dashboard
+    ## Breaking Changes
+    None - orchestrator mode is opt-in via environment variables.
+    ## Migration Guide
+    Existing installations continue to work in standalone mode. To enable orchestrator mode:
+. Deploy an orchestrator server (see ai-orchestrator repo)
+. Generate a connection token from the orchestrator dashboard
+. Add environment variables to your claudecodeui instance
+. Restart claudecodeui - it will automatically connect
+    ---
+    Generated with [Claude Code](https://claude.com/code)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add Orchestrator Client Mode for Remote Access via Central Hub #319

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

feat: Add Orchestrator Client Mode for Remote Access via Central Hub #319

Are you sure you want to change the base?

Uh oh!

feat: Add Orchestrator Client Mode for Remote Access via Central Hub #319

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!