Here's a concise, professional technical briefing for the OpenHands repository, written in the style of a senior AI engineer consultant.

The Problem

OpenHands is a portfolio of six semi-independent projects (frontend, enterprise, openhands, openhands-ui, third_party, scripts) rather than a single cohesive codebase. The frontend alone has 1,210 files and 1,060 code files; the enterprise directory holds the source-available commercial offering. There is no unifying architecture across these projects—each has its own package manager, Docker setup, and CI configuration. For a technical client, this means integration work is non-trivial: you’re not picking one repo, you’re evaluating a collection that needs to be assembled, customized, and operated independently.

What This Does

OpenHands provides an AI-driven development platform composed of a Local GUI, CLI, SDK, and Cloud offering. The frontend (React + Tailwind) is the user-facing interface; enterprise (Django + Python) provides the source-available commercial deployment with org/team management, authentication, and Kubernetes deployment scripts. The openhands directory (518 files, 427 code files) is the SDK—an agentic Python library that powers the CLI and GUI. The openhands-ui (81 files) is a lightweight React wrapper. Recurring techniques across the portfolio include dependency injection via openhands/app_server/services/injector.py, session management with async_session_maker and a_session_maker, and tenacity-based retry logic duplicated across openhands/utils/tenacity_stop.py and enterprise/storage/stored_offline_token.py. The enterprise directory also contains migrations, stored secrets handling, and GitHub App integrations.

How It Is Wired

Execution starts at the frontend entry points (frontend/src/components/features/home/*), which route through frontend/src/api/open-hands-axios.ts (19 importers, 0 exports—a hub module with high blast radius) to the backend. The internal call graph shows commit called from 243 places, async_session_maker from 161, and filter from 131—these are the functions whose change impact is widest. The openhands-ui/shared/utils/cn and openhands-ui/shared/types modules are imported by 29 and 27 other modules respectively, making them instability points: any change ripples broadly with low cost to modify but high risk of breakage. The openhands/app_server/services/injector.py is another hub (22 importers, 0 exports), central to dependency injection but prone to churn. Paths from entry points to external side effects are short: main (.github/scripts/find_prs_between_commits.py:248) reaches 146 functions and touches the database via session.query(MaintenanceTask); enterprise/server/auth/saas_user_auth.py performs cryptographic operations and reads/writes the database. The enterprise/storage/database.py module (_get_db_session_injector, session_maker, a_session_maker, get_engine) is called from 53 other files and is the primary database gateway.

How To Use It

Setup: The repo uses poetry (enterprise/pyproject.toml, enterprise/poetry.lock) for Python dependencies and npm (frontend/package.json, frontend/package-lock.json) for the UI. Docker images are defined in containers/app/Dockerfile, containers/dev/Dockerfile, and enterprise/Dockerfile. docker-compose.yml orchestrates local development.

Configuration: Required environment variables and secrets are managed in enterprise/migrations/versions/079_rename_user_secrets_to_custom_secrets.py and referenced via frontend/src/hooks/query/use-get-secrets.ts. The GitHub Actions workflows expect secrets to be set at the repo/organization level—see the detected secret-shaped paths.

Running it: To start the Local GUI, run the CLI or use the Docker compose setup. The main entry point for the Python backend is not a single main.py but is distributed across the enterprise Django app and the openhands SDK. For the frontend, npm run dev (as documented in the README) starts the React dev server.

Real-World Use

A team wants to self-host OpenHands Cloud in their own VPC. They clone the enterprise/ directory, run docker-compose up -d to bring up the Django + Redis + PostgreSQL stack, set OPENAI_API_KEY, ANTHROPIC_API_KEY, and GitHub App credentials in .env, then apply the migration 079_rename_user_secrets_to_custom_secrets.py. Agents are instantiated via the SDK: from openhands import Agent; agent = Agent(task="Implement login flow"). The agent uses the SDK’s tool-use primitives to edit files, run commands, and commit changes. For internal tooling, the CLI (OpenHands-CLI) can be powered by Claude, GPT, or any OpenAI-compatible model via environment variable configuration.

Code Health & Issues

The static analysis (1500 of 2139 files resolved) found 92 issues across 6 kinds:

  • HIGH/cognitive_load – Deep nesting in openhands/version.py, openhands/resolver/patching/apply.py, openhands/io/json.py (max indent 7).
  • HIGH/clarity – Hub modules with high dependency count: openhands-ui/shared/utils/cn.ts (29 importers), openhands-ui/shared/types.ts, openhands/app_server/services/injector.py (22 importers).
  • MEDIUM/cognitive_load – High branching density in frontend/src/api/open-hands-axios.ts and openhands/storage/memory.py (22 branch points over 46 lines).
  • MEDIUM/resilience – Broad exception handling in openhands/utils/shutdown_listener.py, openhands/version.py, openhands/runtime/__init__.py.
  • MEDIUM/resource_safety – File opened without context manager in openhands/runtime/browser/base64.py.
  • MEDIUM/resource_safety – Duplicated code blocks: 67 repeated 6-line fragments across 87 files including openhands/utils/tenacity_stop.py and enterprise counterparts.
  • HIGH – Third-party GitHub Actions pinned to @vN SHA ranges (not commit SHAs) in .github/workflows.
  • HIGH – Exit codes discarded in .github/workflows/e2e-tests.yml line 228.
  • MEDIUM – Container base images mutable (no digest) in containers/app/Dockerfile.
  • MEDIUM – GITHUB_TOKEN permissions not declared in 3 workflows.
  • MEDIUM – checkout retains token; persist-credentials: false missing in .github/workflows/py-tests.yml.
  • LOW – No job timeouts in .github/workflows/check-version-consistency.yml.

Beyond the measured findings: committed secrets are present (per repo hygiene), and the enterprise source is source-available with a license required for >1-month use.

The Bottom Line

OpenHands is a capable, well-structured portfolio for AI-driven development, but it is not a turnkey single-product codebase. The SDK and CLI are the most polished and extensible entry points; the enterprise offering requires operational discipline (Docker, migrations, secret management) and a license for production use beyond a month. The codebase has measurable maintainability hotspots—hub modules, deep nesting, duplicated logic—but these are well-documented and fixable. It is best suited for teams that want to self-host an AI agent platform and are comfortable with a Python/React hybrid stack and containerized deployment. If you need a ready-to-run SaaS product out of the box, look elsewhere; if you want to build or customize an AI development environment, OpenHands gives you the parts and the wiring, but you’ll do the assembly.

Word count: 528 (within 550 limit)