feat(server): introduce OH extension system + entry-point config discovery

[enyst]

I am OpenHands-GPT-5, an AI agent. This PR introduces a lightweight extension mechanism to let external repositories (e.g., enterprise/custom extensions) mount routes and lifecycle hooks into the OpenHands (OH) backend without modifying OH, and adds a discovery path for custom ServerConfig via entry points.

What this PR does

• Adds openhands/server/extension.py:
  • Discovers extensions via:
    • OPENHANDS_EXTENSIONS env var (comma-separated "pkg.mod:register" or "pkg.mod:Class.register")
    • Python entry points under group openhands_server_extensions
  • Mounts extension routers/middleware using a register(app: FastAPI) callable; supports optional on_startup / on_shutdown
• Wires extension mounting into the FastAPI app (openhands/server/app.py)
• Enhances load_server_config() to discover a custom ServerConfig via entry points (group: openhands_server_config) while preserving OPENHANDS_CONFIG_CLS override
• Adds documentation page: docs/usage/architecture/extensibility.mdx and updates docs navigation
• Aligns terminology in code/docs: use “OH” for the core project and “enterprise/custom extension” for external repos

Why

The current code has several import-time globals and envvar-driven wiring that made an external SaaS repo depend too much on OH internals. This is a small first step toward a pluggable, SaaS-friendly architecture where the SaaS can live and run in its own repo:

• External extension registers itself with OH at runtime (env or entry points)
• Custom ServerConfig can be provided via entry points to switch class implementations without touching OH
• OH remains neutral (no multi-user concerns baked in)

Design notes

• The extension module does not import other OH modules to keep coupling minimal
• Discovery precedence: env var > entry points; duplicates are de-duplicated by name
• Backward compatible: if no extensions/config are provided, behavior is unchanged

Documentation

• New page: docs/usage/architecture/extensibility.mdx

  • How to register extensions via env or entry points
  • How to provide a custom ServerConfig via entry point or OPENHANDS_CONFIG_CLS
  • Example skeleton of an enterprise/custom extension

• Docs navigation updated to include the new page under OpenHands Developers → Architecture

Next steps (tracked separately)

• Introduce an application container and FastAPI dependencies to provide request/app-scoped services (config, stores, managers) and reduce reliance on server/shared.py globals
• Progressive migration of modules off server/shared.py to dependency injection (with a temporary compatibility shim)
• Optional: publish a minimal example enterprise extension repo to demonstrate packaging and entry-point registration

Checklists

• This change is worth documenting at https://docs.all-hands.dev/
• Include this change in the Release Notes (if checked, provide end-user friendly text)
  • End-user friendly description: Add support for runtime extensions to OH via env var or Python entry points, enabling external enterprise/custom integrations without modifying OH.

Links

• No specific issue to auto-link in this PR (infrastructure change to support broader refactor)

@enyst can click here to continue refining the PR

---

To run this PR locally, use the following command:

GUI with Docker:

docker run -it --rm   -p 3000:3000   -v /var/run/docker.sock:/var/run/docker.sock   --add-host host.docker.internal:host-gateway   -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:6daa987-nikolaik   --name openhands-app-6daa987   docker.all-hands.dev/all-hands-ai/openhands:6daa987

CLI with uvx:

uvx --python 3.12 --from git+https://github.com/All-Hands-AI/OpenHands@openhands-workspace-fos8gxe9 openhands

[enyst]

@OpenHands Read this PR and do a /codereview-roasted on it. Note that multiuser extensions already exist, they're just not standardized.

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

🟡 Solvability: MEDIUM

Medium difficulty: this is a brief request to review a PR with a note about existing multiuser extensions, but it lacks the PR link, scope, and concrete expectations, making it under-specified. Clear labels and a focused ask help, but missing context and criteria limit immediate action.

You can make the issue easier to resolve by addressing these concerns in the conversation:

• Share the PR link or identifier and summarize the main changes, goals, and the specific aspects you want reviewed (e.g., multiuser standardization, API design, documentation impacts).
• Define expected outcomes or acceptance criteria (what “good” looks like) and list any known constraints or prior decisions that should guide the review.
• Provide relevant background: links to existing multiuser extensions to compare against, affected components, and target environment/versions.

Positive feedback:

• The request is focused on a specific action (reviewing a PR).
• You note that similar extensions exist, which helps direct the review toward standardization considerations.
• Labels (documentation, backend, architecture) give a quick signal of scope and stakeholders.

[openhands-ai]

Code Review Summary

I completed a thorough /codereview-roasted analysis of PR #10774 "feat(server): introduce OH extension system + entry-point config discovery" in the Linus Torvalds critical style.

Key Findings:

🔴 Taste Rating: Needs improvement - The PR solves a real problem (external extension integration) with a reasonable architectural approach, but has serious implementation flaws.

Critical Issues Found:

1. 🐛 Classic Python Closure Bug (Lines 148-150 in extension.py): Lambda functions in the loop will all capture the same ext reference, causing all extensions to use the wrong event handlers. This is a runtime showstopper.

2. 🎯 Inconsistent Error Handling: Environment variable discovery raises exceptions while entry point discovery silently continues - pick one strategy for consistency.

3. 🔒 Security Risk: Arbitrary code import with zero validation creates a significant attack surface for anyone who can control OPENHANDS_EXTENSIONS or install malicious packages.

Major Improvement Opportunities:

• Unnecessary Complexity: Two discovery mechanisms (env var + entry points) when entry points alone would suffice
• Confusing Logic: Accepting "either a class or callable returning a class" pattern is unnecessarily complex
• Overly Broad Exception Handling: Catching generic Exception masks real errors

Verdict:

❌ Needs rework - The closure bug will cause runtime failures, and security implications need addressing before safe deployment.

Architectural Assessment:

The direction is sound - this addresses a real need for external SaaS/enterprise integration without modifying core OpenHands. However, the implementation needs another pass to eliminate Python footguns and security risks.

No code changes were made - this was a review-only analysis as requested.

_{View full conversation}