Installation

Installation Methods

Using uv (recommended)
Executable Binary
Using Docker

Requires Python 3.12+ and uv installed.Install OpenHands:

uv tool install openhands --python 3.12

Run OpenHands:

openhands

Upgrade OpenHands:

uv tool upgrade openhands --python 3.12

Install the OpenHands CLI binary with the install script:

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

Then run:

openhands

Your system may require you to allow permissions to run the executable.

MacOS

When running the OpenHands CLI on Mac, you may get a warning that says “openhands can’t be opened because Apple cannot check it for malicious software.”

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

Set the following environment variable in your terminal:
- SANDBOX_VOLUMES to specify the directory you want OpenHands to access (See using SANDBOX_VOLUMES for more info)
Ensure you have configured your settings before starting:
- Set up ~/.openhands/settings.json with your LLM configuration
Run the following command:

docker run -it \
    --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.openhands.dev/openhands/runtime:1.1-nikolaik \
    -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"

The -e SANDBOX_USER_ID=$(id -u) is passed to the Docker command to ensure the sandbox user matches the host user’s permissions. This prevents the agent from creating root-owned files in the mounted workspace.

First Run

The first time you run the CLI, it will take you through configuring the required LLM settings. These will be saved for future sessions in ~/.openhands/settings.json. The conversation history will be saved in ~/.openhands/conversations.

If you’re upgrading from a CLI version before release 1.0.0, you’ll need to redo your settings setup as the configuration format has changed.

Next Steps

Quick Start - Learn the basics of using the CLI
MCP Servers - Configure MCP servers

Getting Started

Ways to Run

Cloud

Extensions

Reference

Installation Methods

First Run

Next Steps

Getting Started

Ways to Run

Cloud

Extensions

Reference

​Installation Methods

​First Run

​Next Steps

Installation Methods

First Run

Next Steps