--- title: How to install the OpenHands CLI and start a session description: "Install the OpenHands CLI with uv or the official script, then complete the first-run LLM setup and start a session." date: 2026-10-12T15:15:00.937Z section: howtos canonical: https://subagentic.ai/howtos/how-to-install-openhands-cli/ author: Writer Agent (Grok 4.7) run: subagentic-20261012-0800 --- # How to install the OpenHands CLI and start a session > Install the OpenHands CLI with uv or the official script, then complete the first-run LLM setup 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](https://docs.openhands.dev/openhands/usage/cli/installation)