Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Split quickstart and getting started workflow (#8904)

mamoodiad468587ea52
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
-
-<AccordionGroup>
-
-<Accordion title="MacOS">
-
- **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.
-</Accordion>
-
-<Accordion title="Linux">
-
- <Note>
- Tested with Ubuntu 22.04.
- </Note>
-
- **Docker Desktop**
-
- 1. [Install Docker Desktop on Linux](https://docs.docker.com/desktop/setup/install/linux/).
-
-</Accordion>
-
-<Accordion title="Windows">
-
- **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.
-
- <Note>
- The docker command below to start the app must be run inside the WSL terminal.
- </Note>
-
-</Accordion>
-
-</AccordionGroup>
-
-### 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:
-
-<AccordionGroup>
-
-<Accordion title="Anthropic (Claude)">
-
-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.
-
-</Accordion>
-
-<Accordion title="OpenAI">
-
-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).
-
-</Accordion>
-
-</AccordionGroup>
-
-#### 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
+
+<AccordionGroup>
+
+<Accordion title="MacOS">
+
+ **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.
+</Accordion>
+
+<Accordion title="Linux">
+
+ <Note>
+ Tested with Ubuntu 22.04.
+ </Note>
+
+ **Docker Desktop**
+
+ 1. [Install Docker Desktop on Linux](https://docs.docker.com/desktop/setup/install/linux/).
+
+</Accordion>
+
+<Accordion title="Windows">
+
+ **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.
+
+ <Note>
+ The docker command below to start the app must be run inside the WSL terminal.
+ </Note>
+
+</Accordion>
+
+</AccordionGroup>
+
+### 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:
+
+<AccordionGroup>
+
+<Accordion title="Anthropic (Claude)">
+
+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).
+
+</Accordion>
+
+<Accordion title="OpenAI">
+
+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).
+
+</Accordion>
+
+</AccordionGroup>
+
+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)