From ad468587ea5231cfb524ba8401eb544ebe091a47 Mon Sep 17 00:00:00 2001 From: mamoodi Date: Thu, 5 Jun 2025 10:01:36 -0400 Subject: [PATCH] Split quickstart and getting started workflow (#8904) --- docs/docs.json | 3 +- docs/usage/cloud/openhands-cloud.mdx | 5 +- docs/usage/installation.mdx | 164 +-------------------------- docs/usage/local-setup.mdx | 143 +++++++++++++++++++++++ 4 files changed, 152 insertions(+), 163 deletions(-) create mode 100644 docs/usage/local-setup.mdx diff --git a/docs/docs.json b/docs/docs.json index ef640d6f50..d0cc0ce1d2 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -43,8 +43,9 @@ ] }, { - "group": "Usage Methods", + "group": "Running OpenHands Locally", "pages": [ + "usage/local-setup", "usage/how-to/gui-mode", "usage/how-to/cli-mode", "usage/how-to/headless-mode", diff --git a/docs/usage/cloud/openhands-cloud.mdx b/docs/usage/cloud/openhands-cloud.mdx index 38075239dd..3a3b028bde 100644 --- a/docs/usage/cloud/openhands-cloud.mdx +++ b/docs/usage/cloud/openhands-cloud.mdx @@ -3,11 +3,10 @@ title: Getting Started description: Getting started with OpenHands Cloud --- -OpenHands Cloud is the hosted cloud version of All Hands AI's OpenHands. - ## Accessing OpenHands Cloud -To get started with OpenHands Cloud, visit [app.all-hands.dev](https://app.all-hands.dev). +OpenHands Cloud is the hosted cloud version of All Hands AI's OpenHands. To get started with OpenHands Cloud, +visit [app.all-hands.dev](https://app.all-hands.dev). You'll be prompted to connect with your GitHub or GitLab account: diff --git a/docs/usage/installation.mdx b/docs/usage/installation.mdx index e28cb59510..6579025782 100644 --- a/docs/usage/installation.mdx +++ b/docs/usage/installation.mdx @@ -1,6 +1,6 @@ --- title: Quick Start -description: Running OpenHands on the cloud or your local desktop +description: Running OpenHands Cloud or running on your local system. icon: rocket --- @@ -10,164 +10,10 @@ The easiest way to get started with OpenHands is on OpenHands Cloud, which comes To get started with OpenHands Cloud, visit [app.all-hands.dev](https://app.all-hands.dev). -You'll be prompted to connect with your GitHub or GitLab account: +For more information see [getting started with OpenHands Cloud.](/usage/cloud/openhands-cloud) -1. Click `Log in with GitHub` or `Log in with GitLab`. -2. Review the permissions requested by OpenHands and authorize the application. - - OpenHands will require certain permissions from your account. To read more about these permissions, - you can click the `Learn more` link on the authorization page. +## Running OpenHands Locally +Run OpenHands on your local system and bring your own LLM and API key. -Once you've connected your account, you can: - -- [Install GitHub Integration](/usage/cloud/github-installation) to use OpenHands with your GitHub repositories -- [Install GitLab Integration](/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories -- [Access the Cloud UI](/usage/cloud/cloud-ui) to interact with the web interface -- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands -- [Set up the Cloud Issue Resolver](/usage/cloud/cloud-issue-resolver) to automate code fixes and provide intelligent assistance - - -## Running OpenHands on your local desktop - -### System Requirements - -- MacOS with [Docker Desktop support](https://docs.docker.com/desktop/setup/install/mac-install/#system-requirements) -- Linux -- Windows with [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) and [Docker Desktop support](https://docs.docker.com/desktop/setup/install/windows-install/#system-requirements) - -A system with a modern processor and a minimum of **4GB RAM** is recommended to run OpenHands. - -### Prerequisites - - - - - - **Docker Desktop** - - 1. [Install Docker Desktop on Mac](https://docs.docker.com/desktop/setup/install/mac-install). - 2. Open Docker Desktop, go to `Settings > Advanced` and ensure `Allow the default Docker socket to be used` is enabled. - - - - - - Tested with Ubuntu 22.04. - - - **Docker Desktop** - - 1. [Install Docker Desktop on Linux](https://docs.docker.com/desktop/setup/install/linux/). - - - - - - **WSL** - - 1. [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install). - 2. Run `wsl --version` in powershell and confirm `Default Version: 2`. - - **Docker Desktop** - - 1. [Install Docker Desktop on Windows](https://docs.docker.com/desktop/setup/install/windows-install). - 2. Open Docker Desktop, go to `Settings` and confirm the following: - - General: `Use the WSL 2 based engine` is enabled. - - Resources > WSL Integration: `Enable integration with my default WSL distro` is enabled. - - - The docker command below to start the app must be run inside the WSL terminal. - - - - - - -### Start the App - -The easiest way to run OpenHands is in Docker. - -```bash -docker pull docker.all-hands.dev/all-hands-ai/runtime:0.40-nikolaik - -docker run -it --rm --pull=always \ - -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.40-nikolaik \ - -e LOG_ALL_EVENTS=true \ - -v /var/run/docker.sock:/var/run/docker.sock \ - -v ~/.openhands-state:/.openhands-state \ - -p 3000:3000 \ - --add-host host.docker.internal:host-gateway \ - --name openhands-app \ - docker.all-hands.dev/all-hands-ai/openhands:0.40 -``` - -You'll find OpenHands running at http://localhost:3000! - -You can also [connect OpenHands to your local filesystem](https://docs.all-hands.dev/modules/usage/runtimes/docker#connecting-to-your-filesystem), -run OpenHands in a scriptable [headless mode](https://docs.all-hands.dev/modules/usage/how-to/headless-mode), -interact with it via a [friendly CLI](https://docs.all-hands.dev/modules/usage/how-to/cli-mode), -or run it on tagged issues with [a GitHub action](https://docs.all-hands.dev/modules/usage/how-to/github-action). - -### Setup - -After launching OpenHands, you **must** select an `LLM Provider` and `LLM Model` and enter a corresponding `API Key`. -This can be done during the initial settings popup or by selecting the `Settings` -button (gear icon) in the UI. - -If the required model does not exist in the list, in `Settings` under the `LLM` tab, you can toggle `Advanced` options -and manually enter it with the correct prefix in the `Custom Model` text box. -The `Advanced` options also allow you to specify a `Base URL` if required. - -#### Getting an API Key - -OpenHands requires an API key to access most language models. Here's how to get an API key from the recommended providers: - - - - - -1. [Create an Anthropic account](https://console.anthropic.com/). -2. [Generate an API key](https://console.anthropic.com/settings/keys). -3. [Set up billing](https://console.anthropic.com/settings/billing). - -Consider setting usage limits to control costs. - - - - - -1. [Create an OpenAI account](https://platform.openai.com/). -2. [Generate an API key](https://platform.openai.com/api-keys). -3. [Set up billing](https://platform.openai.com/account/billing/overview). - - - - - -#### Setting Up Search Engine - -OpenHands can be configured to use a search engine to allow the agent to search the web for information when needed. - -Search functionality is enabled by default in OpenHands Cloud. No additional setup is required. - -To enable search functionality in self-hosted OpenHands: - -1. Get a Tavily API key from [tavily.com](https://tavily.com/) -2. Enter the API key in the Settings page under `LLM` tab, `Search API Key (Tavily)` - -For more details, see the [Search Engine Setup](/usage/search-engine-setup) guide. - - -Now you're ready to [get started with OpenHands](./getting-started). - -#### Versions - -The [docker command above](./installation#start-the-app) pulls the most recent stable release of OpenHands. You have other options as well: -- For a specific release, replace `$VERSION` in `openhands:$VERSION` and `runtime:$VERSION`, with the version number. -We use SemVer so `0.9` will automatically point to the latest `0.9.x` release, and `0` will point to the latest `0.x.x` release. -- For the most up-to-date development version, replace `$VERSION` in `openhands:$VERSION` and `runtime:$VERSION`, with `main`. -This version is unstable and is recommended for testing or development purposes only. - -For the development workflow, see [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md). - -Are you having trouble? Check out our [Troubleshooting Guide](https://docs.all-hands.dev/modules/usage/troubleshooting). +For more information see [running OpenHands locally.](/usage/local-setup) diff --git a/docs/usage/local-setup.mdx b/docs/usage/local-setup.mdx new file mode 100644 index 0000000000..81d189792f --- /dev/null +++ b/docs/usage/local-setup.mdx @@ -0,0 +1,143 @@ +--- +title: Getting Started +description: Getting started with running OpenHands locally. +--- + +## Recommended Methods for Running Openhands on Your Local System + +### System Requirements + +- MacOS with [Docker Desktop support](https://docs.docker.com/desktop/setup/install/mac-install/#system-requirements) +- Linux +- Windows with [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) and [Docker Desktop support](https://docs.docker.com/desktop/setup/install/windows-install/#system-requirements) + +A system with a modern processor and a minimum of **4GB RAM** is recommended to run OpenHands. + +### Prerequisites + + + + + + **Docker Desktop** + + 1. [Install Docker Desktop on Mac](https://docs.docker.com/desktop/setup/install/mac-install). + 2. Open Docker Desktop, go to `Settings > Advanced` and ensure `Allow the default Docker socket to be used` is enabled. + + + + + + Tested with Ubuntu 22.04. + + + **Docker Desktop** + + 1. [Install Docker Desktop on Linux](https://docs.docker.com/desktop/setup/install/linux/). + + + + + + **WSL** + + 1. [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install). + 2. Run `wsl --version` in powershell and confirm `Default Version: 2`. + + **Docker Desktop** + + 1. [Install Docker Desktop on Windows](https://docs.docker.com/desktop/setup/install/windows-install). + 2. Open Docker Desktop, go to `Settings` and confirm the following: + - General: `Use the WSL 2 based engine` is enabled. + - Resources > WSL Integration: `Enable integration with my default WSL distro` is enabled. + + + The docker command below to start the app must be run inside the WSL terminal. + + + + + + +### Start the App + +```bash +docker pull docker.all-hands.dev/all-hands-ai/runtime:0.40-nikolaik + +docker run -it --rm --pull=always \ + -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.40-nikolaik \ + -e LOG_ALL_EVENTS=true \ + -v /var/run/docker.sock:/var/run/docker.sock \ + -v ~/.openhands-state:/.openhands-state \ + -p 3000:3000 \ + --add-host host.docker.internal:host-gateway \ + --name openhands-app \ + docker.all-hands.dev/all-hands-ai/openhands:0.40 +``` + +You'll find OpenHands running at http://localhost:3000! + +### Setup + +After launching OpenHands, you **must** select an `LLM Provider` and `LLM Model` and enter a corresponding `API Key`. +This can be done during the initial settings popup or by selecting the `Settings` +button (gear icon) in the UI. + +If the required model does not exist in the list, in `Settings` under the `LLM` tab, you can toggle `Advanced` options +and manually enter it with the correct prefix in the `Custom Model` text box. +The `Advanced` options also allow you to specify a `Base URL` if required. + +#### Getting an API Key + +OpenHands requires an API key to access most language models. Here's how to get an API key from the recommended providers: + + + + + +1. [Create an Anthropic account](https://console.anthropic.com/). +2. [Generate an API key](https://console.anthropic.com/settings/keys). +3. [Set up billing](https://console.anthropic.com/settings/billing). + + + + + +1. [Create an OpenAI account](https://platform.openai.com/). +2. [Generate an API key](https://platform.openai.com/api-keys). +3. [Set up billing](https://platform.openai.com/account/billing/overview). + + + + + +Consider setting usage limits to control costs. + +#### Setting Up Search Engine + +OpenHands can be configured to use a search engine to allow the agent to search the web for information when needed. + +To enable search functionality in OpenHands: + +1. Get a Tavily API key from [tavily.com](https://tavily.com/). +2. Enter the Tavily API key in the Settings page under `LLM` tab > `Search API Key (Tavily)` + +For more details, see the [Search Engine Setup](/usage/search-engine-setup) guide. + + +Now you're ready to [get started with OpenHands](/usage/getting-started). + +### Versions + +The [docker command above](/usage/local-setup#start-the-app) pulls the most recent stable release of OpenHands. You have other options as well: +- For a specific release, replace `$VERSION` in `openhands:$VERSION` and `runtime:$VERSION`, with the version number. +For example, `0.9` will automatically point to the latest `0.9.x` release, and `0` will point to the latest `0.x.x` release. +- For the most up-to-date development version, replace `$VERSION` in `openhands:$VERSION` and `runtime:$VERSION`, with `main`. +This version is unstable and is recommended for testing or development purposes only. + +## Next Steps + +- [Connect OpenHands to your local filesystem.](/usage/runtimes/docker#connecting-to-your-filesystem) to use OpenHands with your GitHub repositories +- [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 tagged issues with a GitHub action.](/usage/how-to/github-action)