Workflow:OpenHands OpenHands SaaS Server Assembly
| Knowledge Sources | |
|---|---|
| Domains | Web_Server, Authentication, SaaS_Platform |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
End-to-end process for assembling, configuring, and starting the OpenHands enterprise SaaS server with authentication middleware, integration routers, and distributed conversation management.
Description
This workflow describes how the OpenHands SaaS enterprise server is constructed from modular components. The server extends the open-source FastAPI base application with Keycloak authentication, Redis-backed rate limiting, clustered conversation management, and integration routers for GitHub, GitLab, Slack, Jira, and Linear. The assembly process configures middleware, registers route handlers, sets up error handling, and serves the React frontend as a single-page application.
Usage
Execute this workflow when deploying the OpenHands enterprise server, whether locally for development, in a staging environment, or in production Kubernetes clusters. This covers the server initialization sequence from configuration loading through request serving.
Execution Steps
Step 1: Base Application Initialization
Start with the core FastAPI application from the open-source openhands.server.app module. This provides the foundational REST API framework, SocketIO integration for real-time communication, and the base conversation management interface.
Key considerations:
- The base app is wrapped as an ASGI application via socketio.ASGIApp
- SocketIO provides WebSocket support for real-time conversation streaming
Step 2: Middleware Stack Configuration
Configure the middleware pipeline in order: CORS handling for permitted origins, cache control headers, authentication cookie management via Keycloak, and Redis-backed rate limiting. Each middleware layer processes requests in sequence before they reach route handlers.
Middleware layers:
- CORS: Allows origins from PERMITTED_CORS_ORIGINS environment variable
- Cache Control: CacheControlMiddleware for HTTP caching headers
- Auth Cookie: SetAuthCookieMiddleware for Keycloak JWT session management
- Rate Limiting: Redis-backed rate limit handler with configurable thresholds
Step 3: Authentication and Authorization Setup
Configure Keycloak-based authentication with JWT token validation, cookie-based session management, and token refresh flows. Set up error handlers for NoCredentialsError and ExpiredError that return HTTP 401 responses. Register the authentication and OAuth routers.
Key considerations:
- JWT configuration loaded from SaaS server config
- Webhook signature verification for integration endpoints
- API key authentication as an alternative to cookie-based auth
Step 4: Integration Router Registration
Register route handlers for all supported integrations. Each integration is conditionally enabled based on environment configuration. The integrations follow a consistent pattern with manager, view, service, and callback processor components.
Integration routers:
- GitHub: Webhook events, proxy routes (conditional on APP_CLIENT_ID)
- GitLab: Webhook events, resource management (conditional on configuration)
- Slack: Bot interactions, workspace management
- Jira Cloud: Workspace and issue management
- Jira Data Center: On-premises Jira integration
- Linear: Issue tracking integration
- MCP: Model Context Protocol server patches
Step 5: Business Logic Routes
Register routes for user management, billing, organizations, API keys, conversations, and feedback. These routes implement the core SaaS business logic including subscription management, shared conversations, and organization RBAC.
Route categories:
- User management: SaaS user info, settings, profile
- Billing: Credit retrieval, checkout sessions, payment processing
- Organizations: CRUD, member management, role assignment
- API Keys: Generation, validation, management
- Conversations: Shared conversations and event retrieval
- Email: Verification and notification routes
- Feedback: Conversation rating and feedback collection
- Event webhooks: Batch event processing from runtimes
Step 6: Frontend Serving
Mount the React single-page application from the frontend/build directory as static files. The SPAStaticFiles handler supports HTML5 history API routing, ensuring that all unmatched routes serve the index.html file for client-side routing.
Key considerations:
- Static files served from ./frontend/build
- HTML5 history API fallback for client-side routing
- Development mode may serve from a different path
Step 7: Server Startup and Health Checks
Start the ASGI server with the assembled application. Register readiness check endpoints that verify database connectivity, Redis availability, and runtime API accessibility. Enable debugging routes in non-production environments.
Key considerations:
- Readiness router provides health check endpoints for Kubernetes probes
- Debugging routes are disabled in production
- Server configuration loaded from environment variables