mirror of
https://github.com/OpenHands/OpenHands.git
synced 2025-12-26 05:48:36 +08:00
258 lines
10 KiB
Plaintext
258 lines
10 KiB
Plaintext
---
|
|
title: GUI
|
|
description: High level overview of the Graphical User Interface (GUI) in OpenHands.
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- [OpenHands is running](/usage/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/how-to/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
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
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
|
|
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/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](/usage/search-engine-setup).
|
|
- [Configure MCP servers](/usage/settings/mcp-settings).
|
|
- [Connect to GitHub](/usage/how-to/gui-mode#github-setup), [connect to GitLab](/usage/how-to/gui-mode#gitlab-setup)
|
|
and [connect to Bitbucket](/usage/how-to/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](../prompting/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.](/usage/how-to/headless-mode)
|
|
- [Run OpenHands with a friendly CLI.](/usage/how-to/cli-mode)
|
|
- [Run OpenHands on GitHub issues with a GitHub action.](/usage/how-to/github-action)
|