Getting Started
Running with Python
Note - OpenHands requires Python version 3.12 or higher (Python 3.14 is not currently supported) anduv
for the default fetch
MCP server (more details below).
Recommended: Using uv
We recommend using uv for the best OpenHands experience. uv provides better isolation from your current project’s virtual environment and is required for OpenHands’ default MCP servers.- Install uv (if you haven’t already): See the uv installation guide for the latest installation instructions for your platform.
- Launch OpenHands CLI:
Alternative: Traditional pip installation
Alternative: Traditional pip installation
If you prefer to use pip:Note that you’ll still need
uv
installed for the default MCP servers to work properly.Create shell aliases for easy access across environments
Create shell aliases for easy access across environments
Add the following to your shell configuration file (After adding these lines, reload your shell configuration with
.bashrc
, .zshrc
, etc.):source ~/.bashrc
or source ~/.zshrc
(depending on your shell).Install OpenHands in home directory without global installation
Install OpenHands in home directory without global installation
You can install OpenHands in a virtual environment in your home directory using
uv
:If you have cloned the repository, you can also run the CLI directly using Poetry:poetry run openhands
- Set your model, API key, and other preferences using the UI (or alternatively environment variables, below).
~/.openhands/sessions
.
Running with Docker
-
Set the following environment variables in your terminal:
SANDBOX_VOLUMES
to specify the directory you want OpenHands to access (See using SANDBOX_VOLUMES for more info)LLM_MODEL
- the LLM model to use (e.g.export LLM_MODEL="anthropic/claude-sonnet-4-20250514"
)LLM_API_KEY
- your API key (e.g.export LLM_API_KEY="sk_test_12345"
)
- Run the following command:
If you used OpenHands before version 0.44, you may want to run
mv ~/.openhands-state ~/.openhands
to migrate your
conversation history to the new location.-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.
The conversation history will be saved in ~/.openhands/sessions
.
Interactive CLI Overview
What is CLI Mode?
CLI mode enables real-time interaction with OpenHands agents. You can type natural language tasks, use interactive commands, and receive instant feedback—all inside your terminal.Starting a Conversation
When you start the CLI, you’ll see a welcome message and a prompt (>
). Enter your first task or type a command to
begin your conversation.
Available Commands
You can use the following commands whenever the prompt (>
) is displayed:
Command | Description |
---|---|
/help | Show all available interactive commands and their descriptions |
/exit | Exit the application |
/init | Initialize a new repository for agent exploration |
/status | Show conversation details and usage metrics |
/new | Start a new conversation |
/settings | View and modify current LLM/agent settings |
/resume | Resume the agent if paused |
/mcp | Manage MCP server configuration and view connection errors |
Settings and Configuration
You can update your model, API key, agent, and other preferences interactively using the/settings
command. Just
follow the prompts:
- Basic settings: Choose a model/provider and enter your API key.
- Advanced settings: Set custom endpoints, enable or disable confirmation mode, and configure memory condensation.
config.toml
file in the current directory or ~/.openhands/config.toml
.
Repository Initialization
The/init
command helps the agent understand your project by creating a .openhands/microagents/repo.md
file with
project details and structure. Use this when onboarding the agent to a new codebase.
Agent Pause/Resume Feature
You can pause the agent while it is running by pressingCtrl-P
. To continue the conversation after pausing, simply
type /resume
at the prompt.
MCP Server Management
To configure Model Context Protocol (MCP) servers, you can refer to the documentation on MCP servers and use the/mcp
command in the CLI. This command provides an interactive interface for managing Model Context Protocol (MCP) servers:
- List configured servers: View all currently configured MCP servers (SSE, Stdio, and SHTTP)
- Add new server: Interactively add a new MCP server with guided prompts
- Remove server: Remove an existing MCP server from your configuration
- View errors: Display any connection errors that occurred during MCP server startup
~/.openhands/config.toml
file and will prompt you to restart OpenHands for changes to take effect.
By default, the Fetch MCP server will be automatically configured for OpenHands. You can also enable search engine via the Tavily MCP server by setting the search_api_key
under the [core]
section in the ~/.openhands/config.toml
file.
Example of the config.toml
file with MCP server configuration:
Tips and Troubleshooting
- Use
/help
at any time to see the list of available commands. - If you encounter permission issues, make sure your workspace directory is trusted and all required environment variables are set correctly.
- For advanced LLM configuration, use the advanced options in
/settings
. - When confirmation mode is enabled, the CLI will prompt before sensitive operations. You can type
a
oralways
at the first confirmation prompt to automatically confirm subsequent actions for the current conversation. - If you want to start over, use
/new
to begin a fresh conversation without restarting the CLI.