Description

When importing DockerWorkspace from openhands-workspace in user code outside of the OpenHands UV workspace environment, a RuntimeError is raised even though no image building is being performed. The error occurs because _default_sdk_project_root() is called at module import time.

Error

Traceback (most recent call last):
  File "/root/git/cve-demo/cve_scan.py", line 13, in <module>
    from src.cve_orchestrator import main
  File "/root/git/cve-demo/src/cve_orchestrator.py", line 15, in <module>
    from src.scanner_agent import CVEScanner
  File "/root/git/cve-demo/src/scanner_agent.py", line 12, in <module>
    from openhands.workspace import DockerWorkspace
  File "/root/.asdf/installs/python/3.12.7/lib/python3.12/site-packages/openhands/workspace/__init__.py", line 3, in <module>
    from .docker import DockerWorkspace
  File "/root/.asdf/installs/python/3.12.7/lib/python3.12/site-packages/openhands/workspace/docker/__init__.py", line 3, in <module>
    from .workspace import DockerWorkspace
  File "/root/.asdf/installs/python/3.12.7/lib/python3.12/site-packages/openhands/workspace/docker/workspace.py", line 14, in <module>
    from openhands.agent_server.docker.build import (
  File "/root/.asdf/installs/python/3.12.7/lib/python3.12/site-packages/openhands/agent_server/docker/build.py", line 310, in <module>
    _DEFAULT_GIT_REF, _DEFAULT_GIT_SHA = _git_info()
                                         ^^^^^^^^^^^
  File "/root/.asdf/installs/python/3.12.7/lib/python3.12/site-packages/openhands/agent_server/docker/build.py", line 265, in _git_info
    sdk_root = _default_sdk_project_root()
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/root/.asdf/installs/python/3.12.7/lib/python3.12/site-packages/openhands/agent_server/docker/build.py", line 132, in _default_sdk_project_root
    raise RuntimeError(
RuntimeError: Could not resolve the OpenHands UV workspace root.

Expected repo layout:
  pyproject.toml  (with [tool.uv.workspace].members including openhands/* subprojects)
  openhands-sdk/pyproject.toml
  openhands-tools/pyproject.toml
  openhands-workspace/pyproject.toml
  openhands-agent-server/pyproject.toml

Run this from inside the repo.

Root Cause

In openhands-agent-server/openhands/agent_server/docker/build.py, lines 310-311 call helper functions at module import time:

_DEFAULT_GIT_REF, _DEFAULT_GIT_SHA = _git_info()
_DEFAULT_PACKAGE_VERSION = _package_version()

Both _git_info() (line 265) and _package_version() (line 300) call _default_sdk_project_root(), which raises a RuntimeError when the code is not running inside the OpenHands UV workspace directory structure.

This happens even when the user has no intention of building images and just wants to use DockerWorkspace with pre-built images.

Expected Behavior

_default_sdk_project_root() should only be called when explicitly building images, not during module import. The module-level variables (_DEFAULT_GIT_REF, _DEFAULT_GIT_SHA, _DEFAULT_PACKAGE_VERSION) should be lazily initialized or their computation should be deferred until actually needed for building.

Proposed Solution

1. Lazy initialization: Convert module-level variables to functions or lazy properties that are only computed when needed during actual build operations
2. Conditional computation: Only call _default_sdk_project_root() when build operations are invoked, not at import time
3. Graceful fallback: If SDK root cannot be determined, use sensible defaults (like "unknown") instead of raising an exception at import time

Additional Issue

The openhands-workspace package imports from openhands.agent_server.docker.build but does not list openhands-agent-server as a dependency in its pyproject.toml. This should be added to the dependencies list.

Impact

This bug prevents users from using openhands-workspace in their own projects outside of the OpenHands development environment, which limits the usefulness of the SDK for external developers who want to use pre-built images with DockerWorkspace.

Environment

• Python 3.12.7
• Installing via pip from PyPI (openhands-workspace)
• Using outside of OpenHands repository