DockerWorkspace imports fail outside UV workspace: _default_sdk_project_root() called at module import time

[xingyaoww]

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

[xingyaoww]

@OpenHands can we implement a subclass of DockerWorkspace as DockerDevWorkspace, and we can only build image on the fly for DockerDevWorkspace? Feel free to suggest other names that you think is better.

This means we can pull all the custom docker building logic from DockerWorkspace into DockerDevWorkspace, making DockerWorkspace more robust, and it also means, when ppl are not importing DockerDevWorkspace, we are not trying to get sdk project root.

[openhands-ai]

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

[openhands-ai]

Summary

I've successfully implemented the requested solution to fix issue #1196 by separating Docker workspace functionality into two classes:

✅ Changes Made

1. Created DockerDevWorkspace Subclass

• New file: openhands-workspace/openhands/workspace/docker/dev_workspace.py
• Extends DockerWorkspace with on-the-fly image building capability
• Contains all build-related logic (base_image, target parameters)
• Requires SDK project root (only when used)

2. Simplified DockerWorkspace

• Removed all build imports and logic
• Made server_image optional with validation to ensure it's provided
• Now only works with pre-built images
• No longer requires SDK project root ✨

3. Implemented Lazy Loading

• Added __getattr__ to both __init__.py files
• DockerDevWorkspace is only imported when explicitly requested
• Prevents build module imports when only DockerWorkspace is used
• Solves the import failure outside SDK workspace! ✨

4. Added Comprehensive Tests

• 6 test cases covering both classes
• Verified DockerWorkspace doesn't trigger build imports
• All tests passing ✅

🎯 Result

Before: Importing DockerWorkspace failed outside SDK workspace with RuntimeError

from openhands.workspace import DockerWorkspace  # ❌ RuntimeError

After: Works perfectly anywhere!

from openhands.workspace import DockerWorkspace  # ✅ Works!
ws = DockerWorkspace(server_image="my-image:latest")

For development scenarios with builds:

from openhands.workspace import DockerDevWorkspace  # ✅ Lazy loaded
ws = DockerDevWorkspace(base_image="ubuntu:22.04")

📦 Pull Request

Created PR #1198: #1198

• All pre-commit checks pass
• Ready for review when you are!

_{View full conversation}