From 8f8b70f7fb44e9a0aee944f0b96ba48a15fafe0f Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 16:49:22 +0000
Subject: [PATCH 01/16] Update package name from openhands-ai to openhands

- Update uvx commands to use simplified 'openhands' instead of '--from openhands-ai openhands'
- Change pip install commands from 'openhands-ai' to 'openhands'
- Update shell aliases and installation examples across documentation
- Sync with changes from OpenHands PR #11271

Co-authored-by: openhands <openhands@all-hands.dev>
---
 openhands/usage/run-openhands/cli-mode.mdx    | 10 +++++-----
 openhands/usage/run-openhands/gui-mode.mdx    |  2 +-
 openhands/usage/run-openhands/local-setup.mdx |  8 ++++----
 openhands/usage/runtimes/overview.mdx         |  2 +-
 openhands/usage/windows-without-wsl.mdx       |  2 +-
 5 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 8c235ab4..13acb29a 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -32,7 +32,7 @@ We recommend using [uv](https://docs.astral.sh/uv/) for the best OpenHands exper
 
 2. **Launch OpenHands CLI**:
 ```bash
-uvx --python 3.12 --from openhands-ai openhands
+uvx --python 3.12 openhands
 ```
 
 <AccordionGroup>
@@ -43,7 +43,7 @@ If you prefer to use pip:
 
 ```bash
 # Install OpenHands
-pip install openhands-ai
+pip install openhands
 ```
 
 Note that you'll still need `uv` installed for the default MCP servers to work properly.
@@ -56,8 +56,8 @@ Add the following to your shell configuration file (`.bashrc`, `.zshrc`, etc.):
 
 ```bash
 # Add OpenHands aliases (recommended)
-alias openhands="uvx --python 3.12 --from openhands-ai openhands"
-alias oh="uvx --python 3.12 --from openhands-ai openhands"
+alias openhands="uvx --python 3.12 openhands"
+alias oh="uvx --python 3.12 openhands"
 ```
 
 After adding these lines, reload your shell configuration with `source ~/.bashrc` or `source ~/.zshrc` (depending on your shell).
@@ -74,7 +74,7 @@ cd ~
 uv venv .openhands-venv --python 3.12
 
 # Install OpenHands in the virtual environment
-uv pip install -t ~/.openhands-venv/lib/python3.12/site-packages openhands-ai
+uv pip install -t ~/.openhands-venv/lib/python3.12/site-packages openhands
 
 # Add the bin directory to your PATH in your shell configuration file
 echo 'export PATH="$PATH:$HOME/.openhands-venv/bin"' >> ~/.bashrc  # or ~/.zshrc
diff --git a/openhands/usage/run-openhands/gui-mode.mdx b/openhands/usage/run-openhands/gui-mode.mdx
index 861d3d1c..c68ed957 100644
--- a/openhands/usage/run-openhands/gui-mode.mdx
+++ b/openhands/usage/run-openhands/gui-mode.mdx
@@ -14,7 +14,7 @@ description: High level overview of the Graphical User Interface (GUI) in OpenHa
 You can launch the OpenHands GUI server directly from the command line using the `serve` command:
 
 <Callout type="info">
-**Prerequisites**: You need to have the [OpenHands CLI installed](/usage/run-openhands/cli-mode) first, OR have `uv` installed and run `uvx --python 3.12 --from openhands-ai openhands serve`. Otherwise, you'll need to use Docker directly (see the [Docker section](#using-docker-directly) below).
+**Prerequisites**: You need to have the [OpenHands CLI installed](/usage/run-openhands/cli-mode) first, OR have `uv` installed and run `uvx --python 3.12 openhands serve`. Otherwise, you'll need to use Docker directly (see the [Docker section](#using-docker-directly) below).
 </Callout>
 
 ```bash
diff --git a/openhands/usage/run-openhands/local-setup.mdx b/openhands/usage/run-openhands/local-setup.mdx
index 1801cffc..73c48fcf 100644
--- a/openhands/usage/run-openhands/local-setup.mdx
+++ b/openhands/usage/run-openhands/local-setup.mdx
@@ -84,13 +84,13 @@ See the [uv installation guide](https://docs.astral.sh/uv/getting-started/instal
 **Launch OpenHands**:
 ```bash
 # Launch the GUI server
-uvx --python 3.12 --from openhands-ai openhands serve
+uvx --python 3.12 openhands serve
 
 # Or with GPU support (requires nvidia-docker)
-uvx --python 3.12 --from openhands-ai openhands serve --gpu
+uvx --python 3.12 openhands serve --gpu
 
 # Or with current directory mounted
-uvx --python 3.12 --from openhands-ai openhands serve --mount-cwd
+uvx --python 3.12 openhands serve --mount-cwd
 ```
 
 This will automatically handle Docker requirements checking, image pulling, and launching the GUI server. The `--gpu` flag enables GPU support via nvidia-docker, and `--mount-cwd` mounts your current directory into the container.
@@ -101,7 +101,7 @@ If you prefer to use pip and have Python 3.12+ installed:
 
 ```bash
 # Install OpenHands
-pip install openhands-ai
+pip install openhands
 
 # Launch the GUI server
 openhands serve
diff --git a/openhands/usage/runtimes/overview.mdx b/openhands/usage/runtimes/overview.mdx
index 25ab882c..b11a54fc 100644
--- a/openhands/usage/runtimes/overview.mdx
+++ b/openhands/usage/runtimes/overview.mdx
@@ -25,7 +25,7 @@ OpenHands supports several different runtime environments:
 The following third-party runtimes are available when you install the `third_party_runtimes` extra:
 
 ```bash
-pip install openhands-ai[third_party_runtimes]
+pip install openhands[third_party_runtimes]
 ```
 
 - [E2B Runtime](/usage/runtimes/e2b) - Open source runtime using E2B sandboxes.
diff --git a/openhands/usage/windows-without-wsl.mdx b/openhands/usage/windows-without-wsl.mdx
index f09d874a..a1bad745 100644
--- a/openhands/usage/windows-without-wsl.mdx
+++ b/openhands/usage/windows-without-wsl.mdx
@@ -162,7 +162,7 @@ After installation, restart your PowerShell session to ensure the environment va
 After installing the prerequisites, you can install and run OpenHands with:
 
 ```powershell
-uvx --python 3.12 --from openhands-ai openhands
+uvx --python 3.12 openhands
 ```
 
 ### Troubleshooting CLI Issues

From 0b3aae0e2a03d30912f4c9de8d85595e295f1d36 Mon Sep 17 00:00:00 2001
From: Rohit Malhotra <rohitvinodmalhotra@gmail.com>
Date: Tue, 7 Oct 2025 12:50:20 -0400
Subject: [PATCH 02/16] Apply suggestion from @malhotra5

---
 openhands/usage/runtimes/overview.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/openhands/usage/runtimes/overview.mdx b/openhands/usage/runtimes/overview.mdx
index b11a54fc..25ab882c 100644
--- a/openhands/usage/runtimes/overview.mdx
+++ b/openhands/usage/runtimes/overview.mdx
@@ -25,7 +25,7 @@ OpenHands supports several different runtime environments:
 The following third-party runtimes are available when you install the `third_party_runtimes` extra:
 
 ```bash
-pip install openhands[third_party_runtimes]
+pip install openhands-ai[third_party_runtimes]
 ```
 
 - [E2B Runtime](/usage/runtimes/e2b) - Open source runtime using E2B sandboxes.

From fa3ec1b7f58a7edf1ef78df94b18ce7bebf0b27b Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 16:55:40 +0000
Subject: [PATCH 03/16] Make executable binary the primary CLI installation
 method

- Restructure Getting Started section to prioritize executable binary
- Move uv and pip methods to accordion alternatives
- Simplify instructions and remove verbose explanations
---
 openhands/usage/run-openhands/cli-mode.mdx | 30 ++++++++++++----------
 1 file changed, 16 insertions(+), 14 deletions(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 13acb29a..2d99d72e 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -18,36 +18,38 @@ for scripting.
 
 ## Getting Started
 
-### Running with Python
+### Using Executable Binary (Recommended)
 
-**Note** - OpenHands requires Python version 3.12 or higher (Python 3.14 is not currently supported) and `uv` for the default `fetch` MCP server (more details below).
+1. **Download the executable binary** from [https://github.com/All-Hands-AI/OpenHands/releases](https://github.com/All-Hands-AI/OpenHands/releases)
 
-#### Recommended: Using uv
+2. **Make it executable**:
+```bash
+chmod +x ./openhands
+```
+
+3. **Run the executable**:
+```bash
+./openhands
+```
 
-We recommend using [uv](https://docs.astral.sh/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.
+<AccordionGroup>
 
-1. **Install uv** (if you haven't already):
+<Accordion title="Alternative: Using uv">
 
-   See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for the latest installation instructions for your platform.
+Requires Python 3.12+ and uv installed.
 
-2. **Launch OpenHands CLI**:
 ```bash
 uvx --python 3.12 openhands
 ```
 
-<AccordionGroup>
-
-<Accordion title="Alternative: Traditional pip installation">
+</Accordion>
 
-If you prefer to use pip:
+<Accordion title="Alternative: pip installation">
 
 ```bash
-# Install OpenHands
 pip install openhands
 ```
 
-Note that you'll still need `uv` installed for the default MCP servers to work properly.
-
 </Accordion>
 
 <Accordion title="Create shell aliases for easy access across environments">

From 4a12b9244f918f219cecc395c9644a9e8366e7a7 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 17:02:42 +0000
Subject: [PATCH 04/16] Update CLI page title to 'CLI (V1)' and add migration
 note

- Change page title from 'CLI' to 'CLI (V1)'
- Add note about settings migration for users upgrading from pre-1.X.X versions
---
 openhands/usage/run-openhands/cli-mode.mdx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 2d99d72e..08c19bcf 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -1,5 +1,5 @@
 ---
-title: CLI
+title: CLI (V1)
 description: The Command-Line Interface (CLI) provides a powerful interface that lets you engage with OpenHands
   directly from your terminal.
 ---
@@ -7,6 +7,10 @@ description: The Command-Line Interface (CLI) provides a powerful interface that
 This mode is different from the [headless mode](/openhands/usage/run-openhands/headless-mode), which is non-interactive and better
 for scripting.
 
+<Note>
+If you're upgrading from a CLI version before release 1.X.X, you'll need to redo your settings setup as the configuration format has changed.
+</Note>
+
 <iframe
   className="w-full aspect-video"
   src="https://www.youtube.com/embed/PfvIx4y8h7w"

From 837045b57e83afe2f7e8e94007dddf29987d9746 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 17:09:48 +0000
Subject: [PATCH 05/16] Remove /init command documentation

- Remove /init command from available commands table
- Remove Repository Initialization section as the command is not currently available
---
 openhands/usage/run-openhands/cli-mode.mdx | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 08c19bcf..675db9bc 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -164,7 +164,6 @@ You can use the following commands whenever the prompt (`>`) is displayed:
 |--------------|----------------------------------------------------------------|
 | `/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                     |
@@ -181,11 +180,6 @@ follow the prompts:
 
 Settings can also be managed via the `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 pressing `Ctrl-P`. To continue the conversation after pausing, simply

From b586d60dde98aca25cde8f8f90897b92ffe4fd79 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 17:10:58 +0000
Subject: [PATCH 06/16] Update configuration file references to use JSON format

- Change settings reference from config.toml to ~/.openhands/settings.json
- Change MCP configuration reference from config.toml to ~/.openhands/mcp.json
- Remove outdated TOML configuration example and search_api_key reference
---
 openhands/usage/run-openhands/cli-mode.mdx | 28 +++-------------------
 1 file changed, 3 insertions(+), 25 deletions(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 675db9bc..249b8b12 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -178,7 +178,7 @@ 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.
 
-Settings can also be managed via the `config.toml` file in the current directory or `~/.openhands/config.toml`.
+Settings can also be managed via the `~/.openhands/settings.json` file.
 
 #### Agent Pause/Resume Feature
 
@@ -194,31 +194,9 @@ To configure Model Context Protocol (MCP) servers, you can refer to the document
 - **Remove server**: Remove an existing MCP server from your configuration
 - **View errors**: Display any connection errors that occurred during MCP server startup
 
-This command modifies your `~/.openhands/config.toml` file and will prompt you to restart OpenHands for changes to take effect.
+This command modifies your `~/.openhands/mcp.json` file and will prompt you to restart OpenHands for changes to take effect.
 
-By default, the [Fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) will be automatically configured for OpenHands. You can also [enable search engine](/openhands/usage/advanced/search-engine-setup) via the [Tavily MCP server](https://github.com/tavily-ai/tavily-mcp) 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:
-
-```toml
-[core]
-search_api_key = "tvly-your-api-key-here"
-
-[mcp]
-stdio_servers = [
-    {name="fetch", command="uvx", args=["mcp-server-fetch"]},
-]
-
-sse_servers = [
-    # Basic SSE server with just a URL
-    "http://example.com:8080/sse",
-]
-
-shttp_servers = [
-    # Streamable HTTP server with API key authentication
-    {url="https://secure-example.com/mcp", api_key="your-api-key"}
-]
-```
+By default, the [Fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) will be automatically configured for OpenHands.
 
 ## Tips and Troubleshooting
 

From c1cd18211781d928e7935a9740dc86bf6fa43e3c Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 17:13:48 +0000
Subject: [PATCH 07/16] Update MCP command documentation to reflect read-only
 functionality

- Change /mcp command description to indicate read-only status viewing
- Update MCP Server Management section to clarify manual configuration requirement
- Reference gofastmcp.com configuration format documentation
- Remove references to interactive MCP server management
---
 openhands/usage/run-openhands/cli-mode.mdx | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 249b8b12..108672e2 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -168,7 +168,7 @@ You can use the following commands whenever the prompt (`>`) is displayed:
 | `/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    |
+| `/mcp`       | View active MCP servers and pending configuration changes     |
 
 #### Settings and Configuration
 
@@ -187,14 +187,12 @@ type `/resume` at the prompt.
 
 #### MCP Server Management
 
-To configure Model Context Protocol (MCP) servers, you can refer to the documentation on [MCP servers](/openhands/usage/settings/mcp-settings) and use the `/mcp` command in the CLI. This command provides an interactive interface for managing Model Context Protocol (MCP) servers:
+To configure Model Context Protocol (MCP) servers, you need to manually create and configure the `~/.openhands/mcp.json` file following the configuration format outlined at [https://gofastmcp.com/clients/client#configuration-format](https://gofastmcp.com/clients/client#configuration-format).
 
-- **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
+The `/mcp` command in the CLI provides a read-only view of MCP server status:
 
-This command modifies your `~/.openhands/mcp.json` file and will prompt you to restart OpenHands for changes to take effect.
+- **View active servers**: Shows which MCP servers are currently active in the conversation
+- **View pending changes**: If the mcp.json file has been modified, shows which servers will be mounted when the conversation is restarted
 
 By default, the [Fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) will be automatically configured for OpenHands.
 

From 64dddb832b6115c0b3ec0e898becb960af78cc8a Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 17:18:26 +0000
Subject: [PATCH 08/16] Add MCP migration note for pre-1.X.X users

- Add note about MCP configuration migration from TOML to JSON format
- Inform users they need to redo MCP settings when upgrading from pre-1.X.X versions
---
 openhands/usage/run-openhands/cli-mode.mdx | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 108672e2..d3747d55 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -187,6 +187,10 @@ type `/resume` at the prompt.
 
 #### MCP Server Management
 
+<Note>
+If you're upgrading from a version before release 1.X.X, you'll need to redo your MCP server configuration as the format has changed from TOML to JSON.
+</Note>
+
 To configure Model Context Protocol (MCP) servers, you need to manually create and configure the `~/.openhands/mcp.json` file following the configuration format outlined at [https://gofastmcp.com/clients/client#configuration-format](https://gofastmcp.com/clients/client#configuration-format).
 
 The `/mcp` command in the CLI provides a read-only view of MCP server status:

From 33b2bb947e1f0108785f813238d627f702ca9177 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 17:19:14 +0000
Subject: [PATCH 09/16] Remove Poetry installation note

- Remove note about running CLI with Poetry for cloned repository
- Simplify installation instructions by focusing on primary methods
---
 openhands/usage/run-openhands/cli-mode.mdx | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index d3747d55..31164022 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -93,12 +93,6 @@ source ~/.bashrc  # or source ~/.zshrc
 
 </AccordionGroup>
 
-<Note>
-  If you have cloned the repository, you can also run the CLI directly using Poetry:
-
-  poetry run openhands
-</Note>
-
 3. Set your model, API key, and other preferences using the UI (or alternatively environment variables, below).
 
 This command opens an interactive prompt where you can type tasks or commands and get responses from OpenHands.

From c6171f9bb238f09393ed36ecaed9863c79be0ef5 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 17:19:48 +0000
Subject: [PATCH 10/16] Remove outdated migration note for version 0.44

- Remove note about migrating ~/.openhands-state to ~/.openhands
- Clean up outdated version-specific migration instructions
---
 openhands/usage/run-openhands/cli-mode.mdx | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 31164022..75222eef 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -126,11 +126,6 @@ docker run -it \
     python -m openhands.cli.entry --override-cli-mode true
 ```
 
-<Note>
-  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.
-</Note>
-
 This launches the CLI in Docker, allowing you to interact with OpenHands.
 
 The `-e SANDBOX_USER_ID=$(id -u)` is passed to the Docker command to ensure the sandbox user matches the host user’s

From 0ca3032311bf2d0cf119240e2d9de9c103ee688d Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 17:21:53 +0000
Subject: [PATCH 11/16] Update conversation storage location in Getting Started
 section

- Change conversation history location from ~/.openhands/sessions to ~/.openhands/conversations
- Update only the Getting Started section as requested
---
 openhands/usage/run-openhands/cli-mode.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 75222eef..97c44b8f 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -99,7 +99,7 @@ This command opens an interactive prompt where you can type tasks or commands an
 The first time you run the CLI, it will take you through configuring the required LLM
 settings. These will be saved for future sessions.
 
-The conversation history will be saved in `~/.openhands/sessions`.
+The conversation history will be saved in `~/.openhands/conversations`.
 
 ### Running with Docker
 

From 1bc7a100ea18b841c257afcb3b75eab4c185ab57 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 17:43:22 +0000
Subject: [PATCH 12/16] Update Docker CLI command to use separate CLI
 installation

- Switch from openhands runtime image to python:3.12-slim base image
- Install CLI via uv package manager inside container
- Adjust volume mount from /.openhands to /root/.openhands for proper settings location
- Remove LLM_API_KEY and LLM_MODEL environment variables (settings now from JSON)
- Update container name to openhands-cli for clarity
- Simplify environment variable setup instructions
---
 openhands/usage/run-openhands/cli-mode.mdx | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 97c44b8f..30cbf5bd 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -103,10 +103,8 @@ The conversation history will be saved in `~/.openhands/conversations`.
 
 ### Running with Docker
 
-1. Set the following environment variables in your terminal:
+1. Set the following environment variable in your terminal:
    - `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access ([See using SANDBOX_VOLUMES for more info](/openhands/usage/runtimes/docker#using-sandbox_volumes))
-   - `LLM_MODEL` - the LLM model to use (e.g. `export LLM_MODEL="anthropic/claude-sonnet-4-20250514"` or `export LLM_MODEL="anthropic/claude-sonnet-4-5-20250929"`)
-   - `LLM_API_KEY` - your API key (e.g. `export LLM_API_KEY="sk_test_12345"`)
 
 2. Run the following command:
 
@@ -116,14 +114,12 @@ docker run -it \
     -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.58-nikolaik \
     -e SANDBOX_USER_ID=$(id -u) \
     -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
-    -e LLM_API_KEY=$LLM_API_KEY \
-    -e LLM_MODEL=$LLM_MODEL \
     -v /var/run/docker.sock:/var/run/docker.sock \
-    -v ~/.openhands:/.openhands \
+    -v ~/.openhands:/root/.openhands \
     --add-host host.docker.internal:host-gateway \
-    --name openhands-app-$(date +%Y%m%d%H%M%S) \
-    docker.all-hands.dev/all-hands-ai/openhands:0.58 \
-    python -m openhands.cli.entry --override-cli-mode true
+    --name openhands-cli-$(date +%Y%m%d%H%M%S) \
+    python:3.12-slim \
+    bash -c "pip install uv && uvx --python 3.12 openhands"
 ```
 
 This launches the CLI in Docker, allowing you to interact with OpenHands.

From 873af0ccccb2f597902c0d67c2db6e7ac4eaf5a6 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 17:46:14 +0000
Subject: [PATCH 13/16] Add configuration setup requirement for Docker CLI

- Add step to ensure settings.json is configured before running Docker command
- Include optional mcp.json configuration note
- Update step numbering to accommodate new configuration step
---
 openhands/usage/run-openhands/cli-mode.mdx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 30cbf5bd..71b06143 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -106,7 +106,11 @@ The conversation history will be saved in `~/.openhands/conversations`.
 1. Set the following environment variable in your terminal:
    - `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access ([See using SANDBOX_VOLUMES for more info](/openhands/usage/runtimes/docker#using-sandbox_volumes))
 
-2. Run the following command:
+2. Ensure you have configured your settings before starting:
+   - Set up `~/.openhands/settings.json` with your LLM configuration
+   - Optionally configure `~/.openhands/mcp.json` for MCP servers (if needed)
+
+3. Run the following command:
 
 ```bash
 docker run -it \

From 7ed9f9a9cbaaa2d7fbe54f08eaf1639064d76e92 Mon Sep 17 00:00:00 2001
From: Rohit Malhotra <rohitvinodmalhotra@gmail.com>
Date: Tue, 7 Oct 2025 15:10:48 -0400
Subject: [PATCH 14/16] Apply suggestion from @malhotra5

---
 openhands/usage/run-openhands/cli-mode.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 71b06143..cd501f6c 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -108,7 +108,7 @@ The conversation history will be saved in `~/.openhands/conversations`.
 
 2. Ensure you have configured your settings before starting:
    - Set up `~/.openhands/settings.json` with your LLM configuration
-   - Optionally configure `~/.openhands/mcp.json` for MCP servers (if needed)
+   - Optionally configure `~/.openhands/mcp.json` for MCP servers
 
 3. Run the following command:
 

From 55f98d41d632f2a996d7e63b1c538b7b56118644 Mon Sep 17 00:00:00 2001
From: openhands <openhands@all-hands.dev>
Date: Tue, 7 Oct 2025 19:15:15 +0000
Subject: [PATCH 15/16] Remove pip install option from CLI mode docs

Co-authored-by: openhands <openhands@all-hands.dev>
---
 openhands/usage/run-openhands/cli-mode.mdx | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index cd501f6c..785b97ad 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -48,14 +48,6 @@ uvx --python 3.12 openhands
 
 </Accordion>
 
-<Accordion title="Alternative: pip installation">
-
-```bash
-pip install openhands
-```
-
-</Accordion>
-
 <Accordion title="Create shell aliases for easy access across environments">
 
 Add the following to your shell configuration file (`.bashrc`, `.zshrc`, etc.):

From 96d073384ea8213aede28e8a1005681894048ace Mon Sep 17 00:00:00 2001
From: Rohit Malhotra <rohitvinodmalhotra@gmail.com>
Date: Fri, 10 Oct 2025 12:48:12 -0400
Subject: [PATCH 16/16] Apply suggestion from @malhotra5

---
 openhands/usage/run-openhands/cli-mode.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/openhands/usage/run-openhands/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
index 785b97ad..294f5cef 100644
--- a/openhands/usage/run-openhands/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -24,7 +24,7 @@ If you're upgrading from a CLI version before release 1.X.X, you'll need to redo
 
 ### Using Executable Binary (Recommended)
 
-1. **Download the executable binary** from [https://github.com/All-Hands-AI/OpenHands/releases](https://github.com/All-Hands-AI/OpenHands/releases)
+1. **Download the executable binary** from [OpenHands release page](https://github.com/All-Hands-AI/OpenHands/releases/tag/1.0.0-cli)
 
 2. **Make it executable**:
 ```bash