Run OpenHands on Your Own
GUI
High level overview of the Graphical User Interface (GUI) in OpenHands.
Prerequisites
Overview
Initial Setup
- Upon first launch, you’ll see a settings popup.
- Select an
LLM ProviderandLLM Modelfrom the dropdown menus. If the required model does not exist in the list, selectsee advanced settings. Then toggleAdvancedoptions and enter it with the correct prefix in theCustom Modeltext box. - Enter the corresponding
API Keyfor your chosen provider. - Click
Save Changesto 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.
GitHub Setup
OpenHands automatically exports aGITHUB_TOKEN to the shell environment if provided:
Setting Up a GitHub Token
Setting Up a GitHub Token
- 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-onlyread for search,Pull Requests = Read and WriteandContent = Read and Writefor branch creation)
- Enter Token in OpenHands:
- In the Settings page, navigate to the
Integrationstab. - Paste your token in the
GitHub Tokenfield. - Click
Save Changesto apply the changes.
- 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.
- Verify Organization Access:
- Go to your token settings on GitHub.
- Look for the organization under
Organization access. - If required, click
Enable SSOnext to your organization. - Complete the SSO authorization process.
Troubleshooting
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.
GitLab Setup
OpenHands automatically exports aGITLAB_TOKEN to the shell environment if provided:
Setting Up a GitLab Token
Setting Up a GitLab Token
- 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.
- Enter Token in OpenHands:
- In the Settings page, navigate to the
Integrationstab. - Paste your token in the
GitLab Tokenfield. - Click
Save Changesto apply the changes.
- (Optional): Restrict agent permissions
- Create another PAT using Step 1 and exclude
apiscope . - In the Settings page, in the
Secretstab, create a new secretGITLAB_TOKENand paste your lower scope token. - OpenHands will use the higher scope token, and the agent will use the lower scope token
Troubleshooting
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.
BitBucket Setup
Setting Up a BitBucket Password
Setting Up a BitBucket Password
- Generate an App Password:
- On BitBucket, go to Personal Settings > App Password.
- Create a new password with the following scopes:
account:readrepository: writepull requests: writeissues: write
- App passwords are non-expiring token. OpenHands will migrate to using API tokens in the future.
- Enter Token in OpenHands:
- In the Settings page, navigate to the
Integrationstab. - Paste your token in the
BitBucket Tokenfield. - Click
Save Changesto apply the changes.
Troubleshooting
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.
Advanced Settings
TheAdvanced 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 Modeltext box to manually enter a model. Make sure to use the correct prefix based on litellm docs. - Base URL: Specify a
Base URLif 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 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 agit 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.
- Use one of the recommended models, as described in the LLMs section.