Merge branch 'main' into kevin

Author: SmartManoj

.github/workflows/openhands-resolver.yml

@@ -83,7 +83,7 @@ jobs:
         (github.event.review.author_association == 'OWNER' || github.event.review.author_association == 'COLLABORATOR' || github.event.review.author_association == 'MEMBER')
         )
       )
-    runs-on: "${{ inputs.runner }}"
+    runs-on: "${{ inputs.runner || 'ubuntu-latest' }}"
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -92,6 +92,9 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+      - name: Upgrade pip
+        run: |
+          python -m pip install --upgrade pip
 
       - name: Get latest versions and create requirements.txt
         run: |
@@ -229,11 +232,11 @@ jobs:
             // Perform package installation
             if (isExperimentalLabel || isIssueCommentExperimental || isReviewCommentExperimental) {
               console.log("Installing experimental OpenHands...");
-              await exec.exec("python -m pip install --upgrade pip");
+
               await exec.exec("pip install git+https://github.com/all-hands-ai/openhands.git");
             } else {
               console.log("Installing from requirements.txt...");
-              await exec.exec("python -m pip install --upgrade pip");
+
               await exec.exec("pip install -r /tmp/requirements.txt");
             }
 

config.template.toml

@@ -258,6 +258,11 @@ enable_history_truncation = true
 # useful when an agent doesn't demand high quality but uses a lot of tokens
 llm_config = 'gpt3'
 
+[agent.CustomAgent]
+# Example: use a custom agent from a different package
+# This will be automatically be registered as a new agent named "CustomAgent"
+classpath = "my_package.my_module.MyCustomAgent"
+
 #################################### Sandbox ###################################
 # Configuration for the sandbox
 ##############################################################################

docs/README.md

@@ -4,37 +4,32 @@ This website is built using [Docusaurus](https://docusaurus.io/).
 
 When published, the content will be published at https://docs.all-hands.dev/.
 
-### Installation
+### Local Development
 
 ```bash
 $ cd docs
-$ yarn
+$ npm install
+$ npm run start
 ```
 
-### Local Development
-
-```
-$ yarn start # for the default English version
-```
-
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+This command starts a local development server and opens up a browser window.
+Most changes are reflected live without having to restart the server.
 
 Alternatively, you can pass a `--locale` argument to render a specific language in dev mode as in:
 
 ```
-$ yarn start --locale pt-BR # for the Brazilian Portuguese version
-$ yarn start --locale fr # for the French version
-$ yarn start --locale zh-Hans # for the Chinese Han (simplified variant) version
+$ npm run start --locale pt-BR # for the Brazilian Portuguese version
+$ npm run start --locale fr # for the French version
+$ npm run start --locale zh-Hans # for the Chinese Han (simplified variant) version
 ```
 
 ### Build
 
 ```
-$ yarn build
+$ npm run build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
 It compiles all languages.
 
 ### Deployment

docs/modules/usage/cloud/_category_.json

@@ -1,6 +1,7 @@
 # OpenHands Cloud API
 
-OpenHands Cloud provides a REST API that allows you to programmatically interact with the service. This is useful if you easily want to kick off your own jobs from your programs in a flexible way.
+OpenHands Cloud provides a REST API that allows you to programmatically interact with the service. This is useful if
+you want to kick off your own jobs from your programs in a flexible way.
 
 This guide explains how to obtain an API key and use the API to start conversations.
 For more detailed information about the API, refer to the [OpenHands API Reference](https://docs.all-hands.dev/swagger-ui/).
@@ -9,27 +10,27 @@ For more detailed information about the API, refer to the [OpenHands API Referen
 
 To use the OpenHands Cloud API, you'll need to generate an API key:
 
-1. Log in to your [OpenHands Cloud](https://app.all-hands.dev) account
-2. Navigate to the [Settings page](https://app.all-hands.dev/settings)
-3. Locate the "API Keys" section
-4. Click "Generate New Key"
-5. Give your key a descriptive name (e.g., "Development", "Production")
-6. Copy the generated API key and store it securely - it will only be shown once
+1. Log in to your [OpenHands Cloud](https://app.all-hands.dev) account.
+2. Navigate to the [Settings page](https://app.all-hands.dev/settings).
+3. Select the `API Keys` tab.
+4. Click `Create API Key`.
+5. Give your key a descriptive name (Example: "Development" or "Production") and select `Create`.
+6. Copy the generated API key and store it securely. It will only be shown once.
 
 ![API Key Generation](/img/docs/api-key-generation.png)
 
 ## API Usage
 
 ### Starting a New Conversation
 
-To start a new conversation with OpenHands performing a task, you'll need to make a POST request to the conversation endpoint.
+To start a new conversation with OpenHands to perform a task, you'll need to make a POST request to the conversation endpoint.
 
 #### Request Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `initial_user_msg` | string | Yes | The initial message to start the conversation |
-| `repository` | string | No | Git repository name to provide context in the format `owner/repo`. You must have access to the repo. |
+| Parameter          | Type     | Required | Description                                                                                          |
+|--------------------|----------|----------|------------------------------------------------------------------------------------------------------|
+| `initial_user_msg` | string   | Yes      | The initial message to start the conversation.                                                       |
+| `repository`       | string   | No       | Git repository name to provide context in the format `owner/repo`. You must have access to the repo. |
 
 #### Examples
 
@@ -126,11 +127,11 @@ The API will return a JSON object with details about the created conversation:
 }
 ```
 
-You may also receive an `AuthenticationError` if:
+You may receive an `AuthenticationError` if:
 
-1. You provided an invalid API key
-2. You provided the wrong repo name
-3. You don't have access to the repo
+- You provided an invalid API key.
+- You provided the wrong repository name.
+- You don't have access to the repository.
 
 
 ### Retrieving Conversation Status

docs/modules/usage/cloud/cloud-api.md

@@ -60,6 +60,6 @@ When using your GitLab account, OpenHands will automatically have access to your
 
 ## Conversation Persistence
 
-- Conversations List – Displays only the 10 most recent conversations initiated within the past 10 days.
+- Conversations List – Displays only the 20 most recent conversations initiated within the past 10 days.
 - Workspaces – Conversation workspaces are retained for 14 days.
 - Runtimes – Runtimes remain active ("warm") for 30 minutes. After this period, resuming a conversation may take 1–2 minutes.

docs/modules/usage/cloud/openhands-cloud.mdx

@@ -1,43 +1,37 @@
 # CLI Mode
 
-OpenHands can be run in an interactive CLI mode, which allows users to start an interactive session via the command line.
+CLI mode provides a powerful interactive Command-Line Interface (CLI) that lets you engage with OpenHands directly
+from your terminal.
 
 This mode is different from the [headless mode](headless-mode), which is non-interactive and better for scripting.
 
-## With Python
+## Getting Started
 
-To start an interactive OpenHands session via the command line:
+### Running with Python
 
 1. Ensure you have followed the [Development setup instructions](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
-2. Run the following command:
+2. Set your model, API key, and other preferences using environment variables or with the [`config.toml`](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml) file.
+3. Launch an interactive OpenHands conversation from the command line:
 
 ```bash
-poetry run python -m openhands.core.cli 
+poetry run python -m openhands.cli.main 
 ```
 
 Example:
 ```bash
-poetry run python -m openhands.core.cli -t "Print 'Hello, World'" --no-auto-continue
+poetry run python -m openhands.cli.main -t "Print 'Hello, World'" --no-auto-continue
 ```
 
-This command will start an interactive session where you can input tasks and receive responses from OpenHands.
-
-You'll need to be sure to set your model, API key, and other settings via environment variables
-[or the `config.toml` file](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml).
-
-## With Docker
+This command opens an interactive prompt where you can type tasks or commands and get responses from OpenHands.
 
-To run OpenHands in CLI mode with Docker:
+### Running with Docker
 
-1. Set the following environmental variables in your terminal:
+1. 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](../runtimes/docker#using-sandbox_volumes))
+   - `LLM_MODEL` - the LLM model to use (e.g. `export LLM_MODEL="anthropic/claude-3-7-sonnet-20250219"`)
+   - `LLM_API_KEY` - your API key (e.g. `export LLM_API_KEY="sk_test_12345"`)
 
-- `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access (Ex: `export SANDBOX_VOLUMES=$(pwd)/workspace:/workspace:rw`).
-  - The agent works in `/workspace` by default, so mount your project directory there if you want the agent to modify files.
-  - For read-only data, use a different mount path (Ex: `export SANDBOX_VOLUMES=$(pwd)/workspace:/workspace:rw,/path/to/large/dataset:/data:ro`).
-- `LLM_MODEL` to the model to use (Ex: `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`).
-- `LLM_API_KEY` to the API key (Ex: `export LLM_API_KEY="sk_test_12345"`).
-
-2. Run the following Docker command:
+2. Run the following command:
 
 ```bash
 docker run -it \
@@ -52,10 +46,65 @@ docker run -it \
     --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.37 \
-    python -m openhands.core.cli
+    python -m openhands.cli.main
 ```
 
-This command will start an interactive session in Docker where you can input tasks and receive responses from OpenHands.
+This launches the CLI in Docker, allowing you to interact with OpenHands as described above.
+
+The `-e SANDBOX_USER_ID=$(id -u)` ensures files created by the agent in your workspace have the correct permissions.
+
+## 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                                     |
+
+#### 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.
+
+Settings can also be managed via the `config.toml` file.
+
+#### 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
+type `/resume` at the prompt.
+
+## 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` or `always` 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.
 
-The `-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.
+---

docs/modules/usage/how-to/cli-mode.md

@@ -39,8 +39,9 @@ OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if pro
      - Minimal Permissions ( Select `Meta Data = Read-only` read for search, `Pull Requests = Read and Write` and `Content = Read and Write` for branch creation)
   2. **Enter Token in OpenHands**:
    - Click the Settings button (gear icon).
+   - Navigate to the `Git` tab.
    - Paste your token in the `GitHub Token` field.
-   - Click `Save` to apply the changes.
+   - Click `Save Changes` to apply the changes.
 </details>
 
 <details>
@@ -98,9 +99,9 @@ OpenHands automatically exports a `GITLAB_TOKEN` to the shell environment if pro
    - Set an expiration date or leave it blank for a non-expiring token.
   2. **Enter Token in OpenHands**:
    - Click the Settings button (gear icon).
+   - Navigate to the `Git` tab.
    - Paste your token in the `GitLab Token` field.
-   - Enter your GitLab instance URL if using self-hosted GitLab.
-   - Click `Save` to apply the changes.
+   - Click `Save Changes` to apply the changes.
 </details>
 
 <details>
@@ -112,7 +113,6 @@ OpenHands automatically exports a `GITLAB_TOKEN` to the shell environment if pro
      - Ensure the token is properly saved in settings.
      - Check that the token hasn't expired.
      - Verify the token has the required scopes.
-     - For self-hosted instances, verify the correct instance URL.
 
   - **Access Denied**:
      - Verify project access permissions.
@@ -122,7 +122,7 @@ OpenHands automatically exports a `GITLAB_TOKEN` to the shell environment if pro
 
 ### Advanced Settings
 
-1. Inside the Settings page, toggle `Advanced` options to access additional settings.
+1. Inside the Settings page, under the `LLM` tab, toggle `Advanced` options to access additional settings.
 2. Use the `Custom Model` text box to manually enter a model if it's not in the list.
 3. Specify a `Base URL` if required by your LLM provider.
 

docs/modules/usage/how-to/gui-mode.md

@@ -21,13 +21,10 @@ You'll need to be sure to set your model, API key, and other settings via enviro
 
 To run OpenHands in Headless mode with Docker:
 
-1. Set the following environmental variables in your terminal:
-
-- `SANDBOX_VOLUMES` to specify the directory you want OpenHands to access (Ex: `export SANDBOX_VOLUMES=$(pwd)/workspace:/workspace:rw`).
-  - The agent works in `/workspace` by default, so mount your project directory there if you want the agent to modify files.
-  - For read-only data, use a different mount path (Ex: `export SANDBOX_VOLUMES=$(pwd)/workspace:/workspace:rw,/path/to/large/dataset:/data:ro`).
-- `LLM_MODEL` to the model to use (Ex: `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`).
-- `LLM_API_KEY` to the API key (Ex: `export LLM_API_KEY="sk_test_12345"`).
+1. 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](../runtimes/docker#using-sandbox_volumes))
+   - `LLM_MODEL` - the LLM model to use (e.g. `export LLM_MODEL="anthropic/claude-3-7-sonnet-20250219"`)
+   - `LLM_API_KEY` - your API key (e.g. `export LLM_API_KEY="sk_test_12345"`)
 
 2. Run the following Docker command:
 

docs/modules/usage/how-to/headless-mode.md

@@ -84,8 +84,8 @@ After launching OpenHands, you **must** select an `LLM Provider` and `LLM Model`
 This can be done during the initial settings popup or by selecting the `Settings`
 button (gear icon) in the UI.
 
-If the required model does not exist in the list, you can toggle `Advanced` options and manually enter it with the correct prefix
-in the `Custom Model` text box.
+If the required model does not exist in the list, in `Settings` under the `LLM` tab, you can toggle `Advanced` options
+and manually enter it with the correct prefix in the `Custom Model` text box.
 The `Advanced` options also allow you to specify a `Base URL` if required.
 
 ### Getting an API Key