How to install the OpenHands CLI and start a session

The OpenHands installation page is enough to get the CLI onto your machine and into a first session. It documents three methods. uv is recommended. An install script provides an executable binary. Docker is a third start, and it expects settings before the container runs. After the uv or script install, the start command is openhands, and the first run configures the required LLM settings.

This guide follows that installation page only. Every command below appears there. Where the page does not specify a prompt, a settings key, or a volume format, the detail is unknown here rather than filled in.

Windows: use the WSL Ubuntu terminal

The page leads with a Windows constraint. All commands below should be run inside the WSL terminal (Ubuntu). From PowerShell, open it with:

wsl -d Ubuntu

You can also search “Ubuntu” in the Start menu and open the Ubuntu terminal from there. The page says a step-by-step video tutorial is available for that Windows path. The video’s clicks are not written out on the installation page, so they are not repeated here.

If you are not on Windows, use your normal terminal. The WSL note is the page’s Windows requirement, not an extra install step for other systems.

Install with uv

The page marks uv as the recommended method. It requires Python 3.12 or newer and uv. The page links to the uv documentation for installing uv. Those uv setup commands are not on the OpenHands installation page, so install uv from the documentation it links before you continue.

Install OpenHands:

uv tool install openhands --python 3.12

Run OpenHands:

openhands

Upgrade later with the command in the same section:

uv tool upgrade openhands --python 3.12

That upgrade line is specific to the uv install. The page does not publish a matching upgrade command for the script or Docker methods.

Install the executable binary

The Executable Binary section installs the CLI with:

curl -fsSL https://install.openhands.dev/install.sh | sh

Then run:

openhands

The page notes that your system may require you to allow permissions to run the executable. It does not list those permission dialogs except for macOS.

macOS security warning

On Mac, you may get a warning that says “openhands can’t be opened because Apple cannot check it for malicious software.” The page’s steps are:

1. Open System Settings.
2. Go to Privacy & Security.
3. Scroll down to Security and click Allow Anyway.
4. Rerun the OpenHands CLI.

A screenshot on the page shows that Security section. After you allow the binary, run openhands again.

Docker, with settings prepared first

The Docker method is a third start path. It is not a substitute for the LLM settings file. The page lists two preparations before the container command.

Set the SANDBOX_VOLUMES environment variable in your terminal to the directory you want OpenHands to access. The installation page points to a separate sandbox document for more on that variable. The syntax of the variable is not written on the installation page, so it is unknown from this page alone.

Ensure you have configured your settings before starting. Set up ~/.openhands/settings.json with your LLM configuration. The installation page does not show the keys inside that file. Do not guess them. This page does not supply the file format.

Then run the published command:

docker run -it \
    --pull=always \
    -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
    -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
    -e SANDBOX_USER_ID=$(id -u) \
    -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands:/root/.openhands \
    --add-host host.docker.internal:host-gateway \
    --name openhands-cli-$(date +%Y%m%d%H%M%S) \
    python:3.12-slim \
    bash -c "pip install uv && uv tool install openhands --python 3.12 && openhands"

Copy it as a whole. The page explains one part in prose: the host user id is passed so the sandbox user matches the host user’s permissions. That prevents the agent from creating root-owned files in the mounted workspace.

The inner command installs uv, installs OpenHands with the same uv tool install used in the recommended path, and then runs openhands. That sequence is inside the Docker command on the page. It is not a separate host-side recipe.

First-run LLM configuration

The first time you run the CLI, it takes you through configuring the required LLM settings. Those settings are saved for future sessions in ~/.openhands/settings.json. Conversation history is saved in ~/.openhands/conversations.

The page does not list the questions you will see. Complete the configuration the CLI presents. After that, the settings file is what future sessions use, and conversation history is stored in the conversations directory named above.

If you are upgrading from a CLI version before release 1.0.0, redo your settings setup. The configuration format has changed. The page does not describe the old format or a migration command, so the documented action is to set the settings up again.

That first-run behavior is what the page describes for the CLI itself. The Docker section is the place that tells you to set up ~/.openhands/settings.json before launch. The volume line in the container command above mounts the host directory that holds those settings into the container.

Start, then read Quick Start

On Windows, open the Ubuntu terminal with wsl -d Ubuntu before any install command on this page.

If Python 3.12+ and uv are installed, use uv tool install openhands --python 3.12, then openhands. Otherwise use the install script, allow the executable if your system requires it, and run openhands. On Mac, use Allow Anyway under Privacy & Security if Apple blocks the binary, then rerun the CLI.

Finish the required LLM settings on that first run. They are written to ~/.openhands/settings.json. Conversations are stored in ~/.openhands/conversations.

Choose the Docker command only when SANDBOX_VOLUMES is set and ~/.openhands/settings.json already contains your LLM configuration. The installation page does not document that JSON on this page.

When the session is up, use the installation page’s Next Steps. It links Quick Start for the basics of using the CLI, and MCP Servers for configuring MCP servers. Read Quick Start next. This installation page does not include those later commands, so do not treat the install as the whole workflow.

Sources

• OpenHands CLI installation