Skip to main content

​
Prerequisites

​
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 --from openhands-ai 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:

​
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:

​
GitHub Setup

OpenHands automatically exports a GITHUB_TOKEN to the shell environment if provided:
  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)
  1. 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.
  1. 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.
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 a GITLAB_TOKEN to the shell environment if provided:
  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.
  1. 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.
  1. (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
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

  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.
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

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 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.
  • Use one of the recommended models, as described in the LLMs section.

​
Other Ways to Run Openhands