Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Restore Windows without WSL documentation (#9090)

Graham Neubig90ae4bda0dd7
diff --git a/docs/usage/local-setup.mdx b/docs/usage/local-setup.mdx
index 6bc4dabdf8..51aa0b2933 100644
--- a/docs/usage/local-setup.mdx
+++ b/docs/usage/local-setup.mdx
@@ -10,6 +10,7 @@ description: Getting started with running OpenHands on your own.
- MacOS with [Docker Desktop support](https://docs.docker.com/desktop/setup/install/mac-install/#system-requirements)
- Linux
- Windows with [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) and [Docker Desktop support](https://docs.docker.com/desktop/setup/install/windows-install/#system-requirements)
+- Windows without WSL (see [Windows Without WSL Guide](/usage/windows-without-wsl))
A system with a modern processor and a minimum of **4GB RAM** is recommended to run OpenHands.
@@ -55,6 +56,10 @@ A system with a modern processor and a minimum of **4GB RAM** is recommended to
The docker command below to start the app must be run inside the WSL terminal.
</Note>
+ **Alternative: Windows without WSL**
+
+ If you prefer to run OpenHands on Windows without WSL or Docker, see our [Windows Without WSL Guide](/usage/windows-without-wsl).
+
</Accordion>
</AccordionGroup>
diff --git a/docs/usage/windows-without-wsl.mdx b/docs/usage/windows-without-wsl.mdx
new file mode 100644
index 0000000000..0ebe321b3e
--- /dev/null
+++ b/docs/usage/windows-without-wsl.mdx
@@ -0,0 +1,200 @@
+---
+title: Windows Without WSL
+description: Running OpenHands GUI on Windows without using WSL or Docker
+---
+
+# Running OpenHands GUI on Windows Without WSL
+
+This guide provides step-by-step instructions for running OpenHands on a Windows machine without using WSL or Docker.
+
+## Prerequisites
+
+1. **Windows 10/11** - A modern Windows operating system
+2. **PowerShell 7+** - While Windows PowerShell comes pre-installed on Windows 10/11, PowerShell 7+ is strongly recommended to avoid compatibility issues (see Troubleshooting section for "System.Management.Automation" errors)
+3. **.NET Core Runtime** - Required for the PowerShell integration via pythonnet
+4. **Python 3.12 or 3.13** - Python 3.12 or 3.13 is required (Python 3.14 is not supported due to pythonnet compatibility)
+5. **Git** - For cloning the repository and version control
+6. **Node.js and npm** - For running the frontend
+
+## Step 1: Install Required Software
+
+1. **Install Python 3.12 or 3.13**
+ - Download Python 3.12.x or 3.13.x from [python.org](https://www.python.org/downloads/)
+ - During installation, check "Add Python to PATH"
+ - Verify installation by opening PowerShell and running:
+ ```powershell
+ python --version
+ ```
+
+2. **Install PowerShell 7**
+ - Download and install PowerShell 7 from the [official PowerShell GitHub repository](https://github.com/PowerShell/PowerShell/releases)
+ - Choose the MSI installer appropriate for your system (x64 for most modern computers)
+ - Run the installer with default options
+ - Verify installation by opening a new terminal and running:
+ ```powershell
+ pwsh --version
+ ```
+ - Using PowerShell 7 (pwsh) instead of Windows PowerShell will help avoid "System.Management.Automation" errors
+
+3. **Install .NET Core Runtime**
+ - Download and install the .NET Core Runtime from [Microsoft's .NET download page](https://dotnet.microsoft.com/download)
+ - Choose the latest .NET Core Runtime (not SDK)
+ - Verify installation by opening PowerShell and running:
+ ```powershell
+ dotnet --info
+ ```
+ - This step is required for the PowerShell integration via pythonnet. Without it, OpenHands will fall back to a more limited PowerShell implementation.
+
+4. **Install Git**
+ - Download Git from [git-scm.com](https://git-scm.com/download/win)
+ - Use default installation options
+ - Verify installation:
+ ```powershell
+ git --version
+ ```
+
+5. **Install Node.js and npm**
+ - Download Node.js from [nodejs.org](https://nodejs.org/) (LTS version recommended)
+ - During installation, accept the default options which will install npm as well
+ - Verify installation:
+ ```powershell
+ node --version
+ npm --version
+ ```
+
+6. **Install Poetry**
+ - Open PowerShell as Administrator and run:
+ ```powershell
+ (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
+ ```
+ - Add Poetry to your PATH:
+ ```powershell
+ $env:Path += ";$env:APPDATA\Python\Scripts"
+ ```
+ - Verify installation:
+ ```powershell
+ poetry --version
+ ```
+
+## Step 2: Clone and Set Up OpenHands
+
+1. **Clone the Repository**
+ ```powershell
+ git clone https://github.com/All-Hands-AI/OpenHands.git
+ cd OpenHands
+ ```
+
+2. **Install Dependencies**
+ ```powershell
+ poetry install
+ ```
+
+ This will install all required dependencies, including:
+ - pythonnet - Required for Windows PowerShell integration
+ - All other OpenHands dependencies
+
+## Step 3: Run OpenHands
+
+1. **Build the Frontend**
+ ```powershell
+ cd frontend
+ npm install
+ npm run build
+ cd ..
+ ```
+
+ This will build the frontend files that the backend will serve.
+
+2. **Start the Backend**
+ ```powershell
+ # Make sure to use PowerShell 7 (pwsh) instead of Windows PowerShell
+ pwsh
+ $env:RUNTIME="local"; poetry run uvicorn openhands.server.listen:app --host 0.0.0.0 --port 3000 --reload --reload-exclude "./workspace"
+ ```
+
+ This will start the OpenHands app using the local runtime with PowerShell integration, available at `localhost:3000`.
+
+ > **Note**: If you encounter a `RuntimeError: Directory './frontend/build' does not exist` error, make sure you've built the frontend first using the command above.
+
+ > **Important**: Using PowerShell 7 (pwsh) instead of Windows PowerShell is recommended to avoid "System.Management.Automation" errors. If you encounter this error, see the Troubleshooting section below.
+
+3. **Alternatively, Run the Frontend in Development Mode (in a separate PowerShell window)**
+ ```powershell
+ cd frontend
+ npm run dev
+ ```
+
+4. **Access the OpenHands GUI**
+
+ Open your browser and navigate to:
+ ```
+ http://localhost:3000
+ ```
+
+ > **Note**: If you're running the frontend in development mode (using `npm run dev`), use port 3001 instead: `http://localhost:3001`
+
+## Limitations on Windows
+
+When 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.
+
+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.
+
+4. **Path Handling**: Windows uses backslashes (`\`) in paths, which may require adjustments when working with code examples designed for Unix-like systems.
+
+## Troubleshooting
+
+### "System.Management.Automation" Not Found Error
+
+If you encounter an error message stating that "System.Management.Automation" was not found, this typically indicates that you have a minimal version of PowerShell installed or that the .NET components required for PowerShell integration are missing.
+
+> **IMPORTANT**: This error is most commonly caused by using the built-in Windows PowerShell (powershell.exe) instead of PowerShell 7 (pwsh.exe). Even if you installed PowerShell 7 during the prerequisites, you may still be using the older Windows PowerShell by default.
+
+To resolve this issue:
+
+1. **Install the latest version of PowerShell 7** from the official Microsoft repository:
+ - Visit [https://github.com/PowerShell/PowerShell/releases](https://github.com/PowerShell/PowerShell/releases)
+ - Download and install the latest MSI package for your system architecture (x64 for most systems)
+ - During installation, ensure you select the following options:
+ - "Add PowerShell to PATH environment variable"
+ - "Register Windows PowerShell 7 as the default shell"
+ - "Enable PowerShell remoting"
+ - The installer will place PowerShell 7 in `C:\Program Files\PowerShell\7` by default
+
+2. **Restart your terminal or command prompt** to ensure the new PowerShell is available
+
+3. **Verify the installation** by running:
+ ```powershell
+ pwsh --version
+ ```
+
+ You should see output indicating PowerShell 7.x.x
+
+4. **Run OpenHands using PowerShell 7** instead of Windows PowerShell:
+ ```powershell
+ pwsh
+ cd path\to\openhands
+ $env:RUNTIME="local"; poetry run uvicorn openhands.server.listen:app --host 0.0.0.0 --port 3000 --reload --reload-exclude "./workspace"
+ ```
+
+ > **Note**: Make sure you're explicitly using `pwsh` (PowerShell 7) and not `powershell` (Windows PowerShell). The command prompt or terminal title should say "PowerShell 7" rather than just "Windows PowerShell".
+
+5. **If the issue persists**, ensure that you have the .NET Runtime installed:
+ - Download and install the latest .NET Runtime from [Microsoft's .NET download page](https://dotnet.microsoft.com/download)
+ - Choose ".NET Runtime" (not SDK) version 6.0 or later
+ - After installation, verify it's properly installed by running:
+ ```powershell
+ dotnet --info
+ ```
+ - Restart your computer after installation
+ - Try running OpenHands again
+
+6. **Ensure that the .NET Framework is properly installed** on your system:
+ - Go to Control Panel > Programs > Programs and Features > Turn Windows features on or off
+ - Make sure ".NET Framework 4.8 Advanced Services" is enabled
+ - Click OK and restart if prompted
+
+This error occurs because OpenHands uses the pythonnet package to interact with PowerShell, which requires the System.Management.Automation assembly from the .NET framework. A minimal PowerShell installation or older Windows PowerShell (rather than PowerShell 7+) might not include all the necessary components for this integration.