Run OpenHands agent inside your terminal, favorite IDE, CI pipelines, local browser, or secure OpenHands Cloud sandboxes.
⚠️ This project is no longer actively maintained.
We recommend using Agent Canvas for an entirely open source, customizable, and local AI coding agent experience. See the Agent Canvas installation docs to get started.
Requires Python 3.12+ and uv 0.11.6 or newer.
uv tool install openhands --python 3.12Install the standalone binary with the install script:
curl -fsSL https://install.openhands.dev/install.sh | shThe first time you run the CLI, it will guide you through configuring your LLM settings:
openhandsOpenHands 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).
| 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 |
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>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-approveRun 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"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"openhands --resume # list recent conversations
openhands --resume <id> # resume specific conversation
openhands --resume --last # resume most recentFor complete documentation, visit https://docs.openhands.dev/openhands/usage/cli.
MIT License - see LICENSE for details.
