GUI

High level overview of the Graphical User Interface (GUI) in OpenHands.

Prerequisites

• OpenHands is running

Launching the GUI Server

Using the CLI Command

You can launch the OpenHands GUI server directly from the command line using the serve command:

Prerequisites: You need to have the OpenHands CLI installed first, OR have uv installed and run uvx --python 3.12 openhands serve. Otherwise, you’ll need to use Docker directly (see the Docker section below).

openhands serve

This command will:

• Check that Docker is installed and running
• Pull the required Docker images
• Launch the OpenHands GUI server at http://localhost:3000
• Use the same configuration directory (~/.openhands) as the CLI mode

Mounting Your Current Directory

To mount your current working directory into the GUI server container, use the --mount-cwd flag:

openhands serve --mount-cwd

This is useful when you want to work on files in your current directory through the GUI. The directory will be mounted at /workspace inside the container.

Using GPU Support

If you have NVIDIA GPUs and want to make them available to the OpenHands container, use the --gpu flag:

openhands serve --gpu

This will enable GPU support via nvidia-docker, mounting all available GPUs into the container. You can combine this with other flags:

openhands serve --gpu --mount-cwd

Prerequisites for GPU support:

• NVIDIA GPU drivers must be installed on your host system
• NVIDIA Container Toolkit (nvidia-docker2) must be installed and configured

Requirements

Before using the openhands serve command, ensure that:

• Docker is installed and running on your system
• You have internet access to pull the required Docker images
• Port 3000 is available on your system

The CLI will automatically check these requirements and provide helpful error messages if anything is missing.

Using Docker Directly

Alternatively, you can run the GUI server using Docker directly. See the local setup guide for detailed Docker instructions.

Overview

Initial Setup

1. Upon first launch, you’ll see a settings popup.
2. Select an LLM Provider and LLM Model from the dropdown menus. If the required model does not exist in the list, select see advanced settings. Then toggle Advanced options and enter it with the correct prefix in the Custom Model text box.
3. Enter the corresponding API Key for your chosen provider.
4. Click Save Changes to apply the settings.

Settings

You can use the Settings page at any time to:

• Setup the LLM provider and model for OpenHands.
• Setup the search engine.
• Configure MCP servers.
• Connect to GitHub, connect to GitLab and connect to Bitbucket.
• Set application settings like your preferred language, notifications and other preferences.
• Manage custom secrets.

Key Features

For an overview of the key features available inside a conversation, please refer to the Key Features section of the documentation.

Other Ways to Run Openhands

• Run OpenHands in a scriptable headless mode.
• Run OpenHands with a friendly CLI.
• Run OpenHands on GitHub issues with a GitHub action.