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 | Provenance | Actions |
|---|---|---|---|---|
| openhands-1.16.0.tar.gz | 753.2 kB | Without provenance | Details for openhands-1.16.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openhands-1.16.0-py3-none-any.whl | Python 3 | none | any | Details for openhands-1.16.0-py3-none-any.whl |
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}
|
Security for openhands 1.16.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
