Run OpenHands agent inside your terminal, favorite IDE, CI pipelines, local browser, or secure OpenHands Cloud sandboxes.
Installation
Using uv (Recommended)
Requires Python 3.12+ and uv 0.11.6 or newer.
uv tool install openhands --python 3.12
Executable Binary
Install the standalone binary with the install script:
curl -fsSL https://install.openhands.dev/install.sh | sh
Usage
Quick Start
The first time you run the CLI, it will guide you through configuring your LLM settings:
openhands
Configuration
OpenHands CLI stores configuration under ~/.openhands/ (created on first run):
agent_settings.json: persisted agent settings (including condenser config)cli_config.json: CLI/TUI preferences (e.g., critic enabled)mcp.json: MCP server configuration
By default, environment variables like LLM_API_KEY, LLM_MODEL, and LLM_BASE_URL are ignored; pass --override-with-envs to apply them (not persisted).
Running Modes
| Mode | Command | Best For |
|---|---|---|
| Terminal (TUI) | openhands |
Interactive development |
| IDE Integration | openhands acp |
IDEs (Toad, Zed, VSCode, JetBrains, etc) |
| Headless | openhands --headless -t "task" |
CI, scripts, and automation |
| Web Interface | openhands web |
Browser-based TUI |
| GUI Server | openhands serve |
Full web GUI |
Features
MCP Servers
Extend OpenHands capabilities with Model Context Protocol (MCP) servers:
# List configured servers
openhands mcp list
# Add a server
openhands mcp add tavily --transport stdio \
npx -- -y mcp-remote "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>"
# Enable/disable servers
openhands mcp enable <server-name>
openhands mcp disable <server-name>
Confirmation Modes
Control how the agent handles actions:
# Default: ask for confirmation on each action
openhands
# Auto-approve all actions
openhands --always-approve # or --yolo
# LLM-based security analyzer
openhands --llm-approve
Cloud Conversations
Run tasks on OpenHands Cloud. First, authenticate with OpenHands Cloud to fetch your settings:
# Login to OpenHands Cloud
openhands login
# Run a task on OpenHands Cloud
openhands cloud -t "Fix the login bug"
Headless Mode
Run OpenHands without the interactive UI for CI/CD pipelines and automation:
openhands --headless -t "Write unit tests for auth.py"
openhands --headless -f instructions.md # or use a file
# With JSON output for parsing
openhands --headless --json -t "Create a Flask app"
Resume Conversations
openhands --resume # list recent conversations
openhands --resume <id> # resume specific conversation
openhands --resume --last # resume most recent
Documentation
For complete documentation, visit https://docs.openhands.dev/openhands/usage/cli.
License
MIT License - see LICENSE for details.
Thank You to Our Contributors
Trusted by Engineers at
2 maintainers
Metadata
2 maintainers
Release files for openhands 1.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| openhands-1.16.0.tar.gz | 753.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| openhands-1.16.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 972.1 kB
Release files / openhands-1.16.0.tar.gz
| Download URL | openhands-1.16.0.tar.gz |
|---|---|
| Size | 753.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f3ac39c86b1c0fabcf4d88f9c65c353d9cf83e457063e6b87d67f9a94f832e97
|
|
BLAKE2b-256 checksum How to use checksums |
8e0d755bce6fc7ccaae8b346dee56e73266a710bc994f54f717364287775eede
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.11 {"installer":{"name":"uv","version":"0.11.11","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / openhands-1.16.0-py3-none-any.whl
| Download URL | openhands-1.16.0-py3-none-any.whl |
|---|---|
| Size | 218.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e5495ddc76bff6ad8cf332b2e366c665f6735da31bc60fba9d430e19d11ffd3d
|
|
BLAKE2b-256 checksum How to use checksums |
9baf5a3e5dca3c6e4beaac030bf944227e9efe54c40f3b3eca226d33d4680760
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.11 {"installer":{"name":"uv","version":"0.11.11","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
