Run OpenHands agent inside your terminal, favorite IDE, CI pipelines, local browser, or secure OpenHands Cloud sandboxes.
Requires Python 3.12+ and uv.
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
# 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"
# With JSON output for parsing
openhands --headless --json -t "Create a Flask app"For complete documentation, visit https://docs.openhands.dev/openhands/usage/cli.
MIT License - see LICENSE for details.