π OpenHands: AI-Driven Development
feat: Add Windows PowerShell support to CLI runtime (#9211)
Graham Neubig5d69e606ebdd
diff --git a/docs/usage/windows-without-wsl.mdx b/docs/usage/windows-without-wsl.mdxindex 0ebe321b3e..f09d874a2e 100644--- a/docs/usage/windows-without-wsl.mdx+++ b/docs/usage/windows-without-wsl.mdx@@ -133,13 +133,66 @@ This guide provides step-by-step instructions for running OpenHands on a Windows> **Note**: If you're running the frontend in development mode (using `npm run dev`), use port 3001 instead: `http://localhost:3001`+## Installing and Running the CLI++To install and run the OpenHands CLI on Windows without WSL, follow these steps:++### 1. Install uv (Python Package Manager)++Open PowerShell as Administrator and run:++```powershell+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"+```++### 2. Install .NET SDK (Required)++The OpenHands CLI **requires** the .NET Core runtime for PowerShell integration. Without it, the CLI will fail to start with a `coreclr` error. Install the .NET SDK which includes the runtime:++```powershell+winget install Microsoft.DotNet.SDK.8+```++Alternatively, you can download and install the .NET SDK from the [official Microsoft website](https://dotnet.microsoft.com/download).++After installation, restart your PowerShell session to ensure the environment variables are updated.++### 3. Install and Run OpenHands++After installing the prerequisites, you can install and run OpenHands with:++```powershell+uvx --python 3.12 --from openhands-ai openhands+```++### Troubleshooting CLI Issues++#### CoreCLR Error++If you encounter an error like `Failed to load CoreCLR` or `pythonnet.load('coreclr')` when running OpenHands CLI, this indicates that the .NET Core runtime is missing or not properly configured. To fix this:++1. Install the .NET SDK as described in step 2 above+2. Verify that your system PATH includes the .NET SDK directories+3. Restart your PowerShell session completely after installing the .NET SDK+4. Make sure you're using PowerShell 7 (pwsh) rather than Windows PowerShell++To verify your .NET installation, run:++```powershell+dotnet --info+```++This should display information about your installed .NET SDKs and runtimes. If this command fails, the .NET SDK is not properly installed or not in your PATH.++If the issue persists after installing the .NET SDK, try installing the specific .NET Runtime version 6.0 or later from the [.NET download page](https://dotnet.microsoft.com/download).+## Limitations on WindowsWhen running OpenHands on Windows without WSL or Docker, be aware of the following limitations:1. **Browser Tool Not Supported**: The browser tool is not currently supported on Windows.-2. **.NET Core Requirement**: The PowerShell integration requires .NET Core Runtime to be installed. If .NET Core is not available, OpenHands will automatically fall back to a more limited PowerShell implementation with reduced functionality.+2. **.NET Core Requirement**: The PowerShell integration requires .NET Core Runtime to be installed. The CLI implementation attempts to load the CoreCLR at startup with `pythonnet.load('coreclr')` and will fail with an error if .NET Core is not properly installed.3. **Interactive Shell Commands**: Some interactive shell commands may not work as expected. The PowerShell session implementation has limitations compared to the bash session used on Linux/macOS.diff --git a/openhands/runtime/impl/cli/cli_runtime.py b/openhands/runtime/impl/cli/cli_runtime.pyindex 0b1283ee79..1b076d2084 100644--- a/openhands/runtime/impl/cli/cli_runtime.py+++ b/openhands/runtime/impl/cli/cli_runtime.py@@ -9,11 +9,12 @@ import selectimport shutilimport signalimport subprocess+import sysimport tempfileimport timeimport zipfilefrom pathlib import Path-from typing import Any, Callable+from typing import TYPE_CHECKING, Any, Callablefrom binaryornot.check import is_binaryfrom openhands_aci.editor.editor import OHEditor@@ -51,6 +52,41 @@ from openhands.runtime.base import Runtimefrom openhands.runtime.plugins import PluginRequirementfrom openhands.runtime.runtime_status import RuntimeStatus+if TYPE_CHECKING:+ from openhands.runtime.utils.windows_bash import WindowsPowershellSession++# Import Windows PowerShell support if on Windows+if sys.platform == 'win32':+ try:+ from openhands.runtime.utils.windows_bash import WindowsPowershellSession+ from openhands.runtime.utils.windows_exceptions import DotNetMissingError+ except (ImportError, DotNetMissingError) as err:+ # Print a user-friendly error message without stack trace+ friendly_message = """+ERROR: PowerShell and .NET SDK are required but not properly configured++The .NET SDK and PowerShell are required for OpenHands CLI on Windows.+PowerShell integration cannot function without .NET Core.++Please install the .NET SDK by following the instructions at:+https://docs.all-hands.dev/usage/windows-without-wsl++After installing .NET SDK, restart your terminal and try again.+"""+ print(friendly_message, file=sys.stderr)+ logger.error(+ f'Windows runtime initialization failed: {type(err).__name__}: {str(err)}'+ )+ if (+ isinstance(err, DotNetMissingError)+ and hasattr(err, 'details')+ and err.details+ ):+ logger.debug(f'Details: {err.details}')++ # Exit the program with an error code+ sys.exit(1)+class CLIRuntime(Runtime):"""@@ -119,6 +155,10 @@ class CLIRuntime(Runtime):self.file_editor = OHEditor(workspace_root=self._workspace_path)self._shell_stream_callback: Callable[[str], None] | None = None+ # Initialize PowerShell session on Windows+ self._is_windows = sys.platform == 'win32'+ self._powershell_session: WindowsPowershellSession | None = None+logger.warning('Initializing CLIRuntime. WARNING: NO SANDBOX IS USED. ''This runtime executes commands directly on the local system. '@@ -135,6 +175,15 @@ class CLIRuntime(Runtime):# Change to the workspace directoryos.chdir(self._workspace_path)+ # Initialize PowerShell session if on Windows+ if self._is_windows:+ self._powershell_session = WindowsPowershellSession(+ work_dir=self._workspace_path,+ username=None, # Use current user+ no_change_timeout_seconds=30,+ max_memory_mb=None,+ )+if not self.attach_to_existing:await asyncio.to_thread(self.setup_initial_env)@@ -241,6 +290,40 @@ class CLIRuntime(Runtime):except Exception as e:logger.error(f'Error: {e}')+ def _execute_powershell_command(+ self, command: str, timeout: float+ ) -> CmdOutputObservation | ErrorObservation:+ """+ Execute a command using PowerShell session on Windows.+ Args:+ command: The command to execute+ timeout: Timeout in seconds for the command+ Returns:+ CmdOutputObservation containing the complete output and exit code+ """+ if self._powershell_session is None:+ return ErrorObservation(+ content='PowerShell session is not available.',+ error_id='POWERSHELL_SESSION_ERROR',+ )++ try:+ # Create a CmdRunAction for the PowerShell session+ from openhands.events.action import CmdRunAction++ ps_action = CmdRunAction(command=command)+ ps_action.set_hard_timeout(timeout)++ # Execute the command using the PowerShell session+ return self._powershell_session.execute(ps_action)++ except Exception as e:+ logger.error(f'Error executing PowerShell command "{command}": {e}')+ return ErrorObservation(+ content=f'Error executing PowerShell command "{command}": {str(e)}',+ error_id='POWERSHELL_EXECUTION_ERROR',+ )+def _execute_shell_command(self, command: str, timeout: float) -> CmdOutputObservation:@@ -378,9 +461,16 @@ class CLIRuntime(Runtime):logger.debug(f'Running command in CLIRuntime: "{action.command}" with effective timeout: {effective_timeout}s')- return self._execute_shell_command(- action.command, timeout=effective_timeout- )++ # Use PowerShell on Windows if available, otherwise use subprocess+ if self._is_windows and self._powershell_session is not None:+ return self._execute_powershell_command(+ action.command, timeout=effective_timeout+ )+ else:+ return self._execute_shell_command(+ action.command, timeout=effective_timeout+ )except Exception as e:logger.error(f'Error in CLIRuntime.run for command "{action.command}": {str(e)}'@@ -737,6 +827,16 @@ class CLIRuntime(Runtime):raise RuntimeError(f'Error creating zip file: {str(e)}')def close(self) -> None:+ # Clean up PowerShell session if it exists+ if self._powershell_session is not None:+ try:+ self._powershell_session.close()+ logger.debug('PowerShell session closed successfully.')+ except Exception as e:+ logger.warning(f'Error closing PowerShell session: {e}')+ finally:+ self._powershell_session = None+self._runtime_initialized = Falsesuper().close()diff --git a/openhands/runtime/utils/windows_bash.py b/openhands/runtime/utils/windows_bash.pyindex d777e8c3f3..76c7ff039b 100644--- a/openhands/runtime/utils/windows_bash.py+++ b/openhands/runtime/utils/windows_bash.py@@ -21,21 +21,31 @@ from openhands.events.observation.commands import (CmdOutputObservation,)from openhands.runtime.utils.bash_constants import TIMEOUT_MESSAGE_TEMPLATE+from openhands.runtime.utils.windows_exceptions import DotNetMissingErrorfrom openhands.utils.shutdown_listener import should_continue-pythonnet.load('coreclr')-logger.info("Successfully called pythonnet.load('coreclr')")--# Now that pythonnet is initialized, import clr and Systemtry:- import clr-- logger.debug(f'Imported clr module from: {clr.__file__}')- # Load System assembly *after* pythonnet is initialized- clr.AddReference('System')- import System-except Exception as clr_sys_ex:- raise RuntimeError(f'FATAL: Failed to import clr or System. Error: {clr_sys_ex}')+ pythonnet.load('coreclr')+ logger.info("Successfully called pythonnet.load('coreclr')")++ # Now that pythonnet is initialized, import clr and System+ try:+ import clr++ logger.debug(f'Imported clr module from: {clr.__file__}')+ # Load System assembly *after* pythonnet is initialized+ clr.AddReference('System')+ import System+ except Exception as clr_sys_ex:+ error_msg = 'Failed to import .NET components.'+ details = str(clr_sys_ex)+ logger.error(f'{error_msg} Details: {details}')+ raise DotNetMissingError(error_msg, details)+except Exception as coreclr_ex:+ error_msg = 'Failed to load CoreCLR.'+ details = str(coreclr_ex)+ logger.error(f'{error_msg} Details: {details}')+ raise DotNetMissingError(error_msg, details)# Attempt to load the PowerShell SDK assembly only if clr and System loadedps_sdk_path = None@@ -78,9 +88,10 @@ try:RunspaceState,)except Exception as e:- raise RuntimeError(- f'FATAL: Failed to load PowerShell SDK components. Error: {e}. Check pythonnet installation and .NET Runtime compatibility. Path searched: {ps_sdk_path}'- )+ error_msg = 'Failed to load PowerShell SDK components.'+ details = f'{str(e)} (Path searched: {ps_sdk_path})'+ logger.error(f'{error_msg} Details: {details}')+ raise DotNetMissingError(error_msg, details)class WindowsPowershellSession:@@ -115,9 +126,11 @@ class WindowsPowershellSession:if PowerShell is None: # Check if SDK loading failed during module import# Logged critical error during import, just raise here to prevent instantiation- raise RuntimeError(- 'PowerShell SDK (System.Management.Automation.dll) could not be loaded. Cannot initialize WindowsPowershellSession.'+ error_msg = (+ 'PowerShell SDK (System.Management.Automation.dll) could not be loaded.')+ logger.error(error_msg)+ raise DotNetMissingError(error_msg)self.work_dir = os.path.abspath(work_dir)self.username = usernamediff --git a/openhands/runtime/utils/windows_exceptions.py b/openhands/runtime/utils/windows_exceptions.pynew file mode 100644index 0000000000..bb1917abff--- /dev/null+++ b/openhands/runtime/utils/windows_exceptions.py@@ -0,0 +1,15 @@+"""+Custom exceptions for Windows-specific runtime issues.+"""+++class DotNetMissingError(Exception):+ """+ Exception raised when .NET SDK or CoreCLR is missing or cannot be loaded.+ This is used to provide a cleaner error message to users without a full stack trace.+ """++ def __init__(self, message: str, details: str | None = None):+ self.message = message+ self.details = details+ super().__init__(message)