> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-sdk-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GUI

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

## Prerequisites

* [OpenHands is running](/openhands/usage/run-openhands/local-setup)

## Launching the GUI Server

### Using the CLI Command

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

<Callout type="info">
  **Prerequisites**: You need to have the [OpenHands CLI installed](/usage/run-openhands/cli-mode) first, OR have `uv` installed and run `uvx --python 3.12 --from openhands-ai openhands serve`. Otherwise, you'll need to use Docker directly (see the [Docker section](#using-docker-directly) below).
</Callout>

```bash theme={null}
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](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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
openhands serve --gpu --mount-cwd
```

**Prerequisites for GPU support:**

* NVIDIA GPU drivers must be installed on your host system
* [NVIDIA Container Toolkit (nvidia-docker2)](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) 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](/usage/run-openhands/local-setup) 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](/openhands/usage/advanced/search-engine-setup).
* [Configure MCP servers](/usage/settings/mcp-settings).
* [Connect to GitHub](/usage/run-openhands/gui-mode#github-setup), [connect to GitLab](/usage/run-openhands/gui-mode#gitlab-setup)
  and [connect to Bitbucket](/usage/run-openhands/gui-mode#bitbucket-setup).
* Set application settings like your preferred language, notifications and other preferences.
* [Manage custom secrets](/usage/settings/secrets-settings).

#### GitHub Setup

OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if provided:

<AccordionGroup>
  <Accordion title="Setting Up a GitHub Token">
    1. **Generate a Personal Access Token (PAT)**:

    * On GitHub, go to Settings > Developer Settings > Personal Access Tokens > Tokens (classic).
    * **New token (classic)**
      * Required scopes:
      * `repo` (Full control of private repositories)
    * **Fine-Grained Tokens**
      * All Repositories (You can select specific repositories, but this will impact what returns in repo search)
      * Minimal Permissions (Select `Meta Data = Read-only` read for search, `Pull Requests = Read and Write` and `Content = Read and Write` for branch creation)

    2. **Enter Token in OpenHands**:

    * In the Settings page, navigate to the `Integrations` tab.
    * Paste your token in the `GitHub Token` field.
    * Click `Save Changes` to apply the changes.

    If you're working with organizational repositories, additional setup may be required:

    1. **Check Organization Requirements**:

    * Organization admins may enforce specific token policies.
    * Some organizations require tokens to be created with SSO enabled.
    * Review your organization's [token policy settings](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization).

    2. **Verify Organization Access**:

    * Go to your token settings on GitHub.
    * Look for the organization under `Organization access`.
    * If required, click `Enable SSO` next to your organization.
    * Complete the SSO authorization process.
  </Accordion>

  <Accordion title="Troubleshooting">
    Common issues and solutions:

    * **Token Not Recognized**:
      * Check that the token hasn't expired.
      * Verify the token has the required scopes.
      * Try regenerating the token.

    * **Organization Access Denied**:
      * Check if SSO is required but not enabled.
      * Verify organization membership.
      * Contact organization admin if token policies are blocking access.

    * **Verifying Token Works**:
      * The app will show a green checkmark if the token is valid.
      * Try accessing a repository to confirm permissions.
      * Check the browser console for any error messages.
  </Accordion>
</AccordionGroup>

#### GitLab Setup

OpenHands automatically exports a `GITLAB_TOKEN` to the shell environment if provided:

<AccordionGroup>
  <Accordion title="Setting Up a GitLab Token">
    1. **Generate a Personal Access Token (PAT)**:

    * On GitLab, go to User Settings > Access Tokens.
    * Create a new token with the following scopes:
      * `api` (API access)
      * `read_user` (Read user information)
      * `read_repository` (Read repository)
      * `write_repository` (Write repository)
    * Set an expiration date or leave it blank for a non-expiring token.

    2. **Enter Token in OpenHands**:

    * In the Settings page, navigate to the `Integrations` tab.
    * Paste your token in the `GitLab Token` field.
    * Click `Save Changes` to apply the changes.

    3. **(Optional): Restrict agent permissions**

    * Create another PAT using Step 1 and exclude `api` scope .
    * In the Settings page, in the `Secrets` tab, create a new secret `GITLAB_TOKEN` and paste your lower scope token.
    * OpenHands will use the higher scope token, and the agent will use the lower scope token
  </Accordion>

  <Accordion title="Troubleshooting">
    Common issues and solutions:

    * **Token Not Recognized**:
      * Ensure the token is properly saved in settings.
      * Check that the token hasn't expired.
      * Verify the token has the required scopes.

    * **Access Denied**:
      * Verify project access permissions.
      * Check if the token has the necessary scopes.
      * For group/organization repositories, ensure you have proper access.
  </Accordion>
</AccordionGroup>

#### BitBucket Setup

<AccordionGroup>
  <Accordion title="Setting Up a BitBucket Password">
    1. **Generate an App Password**:
       * On BitBucket, go to Personal Settings > App Password.
       * Create a new password with the following scopes:
         * `account`: `read`
         * `repository: write`
         * `pull requests: write`
         * `issues: write`
       * App passwords are non-expiring token. OpenHands will migrate to using API tokens in the future.
    2. **Enter Token in OpenHands**:

    * In the Settings page, navigate to the `Integrations` tab.
    * Paste your token in the `BitBucket Token` field.
    * Click `Save Changes` to apply the changes.
  </Accordion>

  <Accordion title="Troubleshooting">
    Common issues and solutions:

    * **Token Not Recognized**:
      * Ensure the token is properly saved in settings.
      * Check that the token hasn't expired.
      * Verify the token has the required scopes.

    * **Verifying Token Works**:
      * The app will show a green checkmark if the token is valid.
      * Try accessing a repository to confirm permissions.
      * Check the browser console for any error messages.
  </Accordion>
</AccordionGroup>

#### Advanced Settings

The `Advanced` settings allows configuration of additional LLM settings. Inside the Settings page, under the `LLM` tab,
toggle `Advanced` options to access additional settings.

* Custom Model: Use the `Custom Model` text box to manually enter a model. Make sure to use the correct prefix based on litellm docs.
* Base URL: Specify a `Base URL` if required by your LLM provider.
* Memory Condensation: The memory condenser manages the LLM's context by ensuring only the most important and relevant information is presented.
* Confirmation Mode: Enabling this mode will cause OpenHands to confirm an action with the user before performing it.

### Key Features

For an overview of the key features available inside a conversation, please refer to the [Key Features](/usage/key-features)
section of the documentation.

### Status Indicator

The status indicator located in the bottom left of the screen will cycle through a number of states as a new conversation
is loaded. Typically these include:

* `Disconnected` : The frontend is not connected to any conversation.
* `Connecting` : The frontend is connecting a websocket to a conversation.
* `Building Runtime...` : The server is building a runtime. This is typically in development mode only while building a docker image.
* `Starting Runtime...` : The server is starting a new runtime instance - probably a new docker container or remote runtime.
* `Initializing Agent...` : The server is starting the agent loop (This step does not appear at present with Nested runtimes).
* `Setting up workspace...` : Usually this means a `git clone ...` operation.
* `Setting up git hooks` : Setting up the git pre commit hooks for the workspace.
* `Agent is awaiting user input...` : Ready to go!

## Tips for Effective Use

* Be specific in your requests to get the most accurate and helpful responses, as described in the [prompting best practices](/openhands/usage/tips/prompting-best-practices).
* Use one of the recommended models, as described in the [LLMs section](/usage/llms/llms).

## Other Ways to Run Openhands

* [Run OpenHands in a scriptable headless mode.](/openhands/usage/run-openhands/headless-mode)
* [Run OpenHands with a friendly CLI.](/usage/run-openhands/cli-mode)
* [Run OpenHands on GitHub issues with a GitHub action.](/usage/run-openhands/github-action)