​
OpenHands Cloud

The easiest way to get started with OpenHands is on OpenHands Cloud, which comes with $50 in free credits for new users.

To get started with OpenHands Cloud, visit app.all-hands.dev.

You’ll be prompted to connect with your GitHub or GitLab account:

  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.

Once you’ve connected your account, you can:

​
Running OpenHands on your local desktop

​
System Requirements

A system with a modern processor and a minimum of 4GB RAM is recommended to run OpenHands.

​
Prerequisites

​
Start the App

The easiest way to run OpenHands is in Docker.

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.39-nikolaik

docker run -it --rm --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.39-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.39

You’ll find OpenHands running at http://localhost:3000!

You can also connect OpenHands to your local filesystem, run OpenHands in a scriptable headless mode, interact with it via a friendly CLI, or run it on tagged issues with a 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:

Now you’re ready to get started with OpenHands.

​
Versions

The docker command above 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.

Are you having trouble? Check out our Troubleshooting Guide.