Running OpenHands GUI on Windows

This guide provides step-by-step instructions for running OpenHands on a Windows machine without using WSL or Docker.

Prerequisites

Windows 10/11 - A modern Windows operating system
PowerShell 5.1 or PowerShell 7+ - Windows PowerShell comes pre-installed on Windows 10/11, but PowerShell 7+ is recommended for better compatibility
Python 3.12 - Python 3.12 is required (Python 3.14 is not supported due to pythonnet compatibility)
Git - For cloning the repository and version control

Install Python 3.12
- Download Python 3.12.x from python.org
- During installation, check "Add Python to PATH"
- Verify installation by opening PowerShell and running:
```
python --version
```
Install Git
- Download Git from git-scm.com
- Use default installation options
- Verify installation:
```
git --version
```

Install Poetry

Open PowerShell as Administrator and run:

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

Add Poetry to your PATH:

$env:Path += ";$env:APPDATA\Python\Scripts"

Clone the Repository

git clone https://github.com/All-Hands-AI/OpenHands.git
cd OpenHands

Install Dependencies
```
poetry install
```
This will install all required dependencies, including:
- pythonnet - Required for Windows PowerShell integration
- All other OpenHands dependencies

Install Pre-commit Hooks

poetry run make install-pre-commit-hooks

Set Up Environment Variables

Create a .env file in the root directory with the following content:
```
OPENAI_API_KEY=your_openai_api_key_here
```
Replace your_openai_api_key_here with your actual OpenAI API key.
Configure Frontend (Optional)

If you need to customize the frontend settings, create a .env file in the frontend directory:
```
VITE_BACKEND_HOST=http://localhost:3000
VITE_USE_TLS=false
VITE_FRONTEND_PORT=3001
```

Start the Backend
```
poetry run python -m openhands.cli.main --local-runtime
```
This will start the OpenHands backend using the local runtime with PowerShell integration.
Start the Frontend (in a separate PowerShell window)
```
cd frontend
npm install
npm run dev
```
Access the OpenHands GUI

Open your browser and navigate to:
```
http://localhost:3001
```

When running OpenHands on Windows without WSL or Docker, be aware of the following limitations:

Browser Tool Not Supported: The browser tool is not currently supported on Windows.
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.
Path Handling: Windows uses backslashes (\) in paths, which may require adjustments when working with code examples designed for Unix-like systems.
Performance: Some operations may be slower on Windows compared to Linux/macOS.

If you encounter errors related to Python version compatibility:

If you encounter PowerShell-related errors:

Check your PowerShell version:
```
$PSVersionTable
```
If using Windows PowerShell 5.1, consider upgrading to PowerShell 7+ for better compatibility:
- Download from github.com/PowerShell/PowerShell

Ensure PowerShell execution policy allows running scripts:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

If you encounter errors during dependency installation:

Ensure you have the latest version of Poetry:
```
poetry self update
```
Try clearing Poetry's cache:
```
poetry cache clear --all pypi
```
Install dependencies with verbose output to identify specific issues:
```
poetry install -v
```

If the frontend fails to start or connect to the backend: