Fix unlocalized strings in microagent components

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.devcontainer/devcontainer.json

@@ -12,4 +12,8 @@
 		"ghcr.io/devcontainers/features/node:1": {},
 	},
 	"postCreateCommand": ".devcontainer/setup.sh",
+	"runArgs": ["--add-host=host.docker.internal:host-gateway"],
+	"containerEnv": {
+		"DOCKER_HOST_ADDR": "host.docker.internal"
+	},
 }

.devcontainer/setup.sh

@@ -1,5 +1,9 @@
 #!/bin/bash
 
+# Mark the current repository as safe for Git to prevent "dubious ownership" errors,
+# which can occur in containerized environments when directory ownership doesn't match the current user.
+git config --global --add safe.directory "$(realpath .)"
+
 # Install `nc`
 sudo apt update && sudo apt install netcat -y
 

.dockerignore

@@ -1,5 +1,23 @@
+# NodeJS
 frontend/node_modules
-config.toml
-.envrc
-.env
-.git
+
+# Configuration (except pyproject.toml)
+*.ini
+*.toml
+!pyproject.toml
+*.yml
+
+# Documentation (except README.md)
+*.md
+!README.md
+
+# Hidden files and directories
+.*
+__pycache__
+
+# Unneded files and directories
+/dev_config/
+/docs/
+/evaluation/
+/tests/
+CITATION.cff

.github/CODEOWNERS

@@ -5,7 +5,7 @@
 /frontend/ @rbren @amanape
 
 # Evaluation code owners
-/evaluation/ @xingyaoww @neubig 
+/evaluation/ @xingyaoww @neubig
 
 # Documentation code owners
 /docs/ @mamoodi

.github/ISSUE_TEMPLATE/bug_template.yml

@@ -33,6 +33,7 @@ body:
         - Docker command in README
         - GitHub resolver
         - Development workflow
+        - CLI
         - app.all-hands.dev
         - Other
       default: 0
@@ -44,6 +45,13 @@ body:
       description: What version of OpenHands are you using?
       placeholder: ex. 0.9.8, main, etc.
 
+  - type: input
+    id: model-name
+    attributes:
+      label: Model Name
+      description: What model are you using?
+      placeholder: ex. gpt-4o, claude-3-5-sonnet, openrouter/deepseek-r1, etc.
+
   - type: dropdown
     id: os
     attributes:

.github/dependabot.yml

@@ -16,7 +16,6 @@ updates:
       mcp-packages:
         patterns:
           - "mcp"
-          - "mcpm"
       security-all:
         applies-to: "security-updates"
         patterns:
@@ -73,3 +72,9 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+
+  - package-ecosystem: "docker"
+    directories:
+      - "containers/*"
+    schedule:
+      interval: "weekly"

.github/workflows/ghcr-build.yml

@@ -40,9 +40,7 @@ jobs:
           # Only build nikolaik on PRs, otherwise build both nikolaik and ubuntu.
           if [[ "$GITHUB_EVENT_NAME" == "pull_request" ]]; then
             json=$(jq -n -c '[
-                { image: "nikolaik/python-nodejs:python3.12-nodejs22", tag: "nikolaik" },
-                { image: "ubuntu:24.04", tag: "ubuntu" }
-
+                { image: "nikolaik/python-nodejs:python3.12-nodejs22", tag: "nikolaik" }
               ]')
           else
             json=$(jq -n -c '[
@@ -313,6 +311,8 @@ jobs:
           TEST_IN_CI=true \
           RUN_AS_OPENHANDS=false \
           poetry run pytest -n 7 -raRs --reruns 2 --reruns-delay 5 -s ./tests/runtime --ignore=tests/runtime/test_browsergym_envs.py --durations=10
+        env:
+          DEBUG: "1"
 
   # Run unit tests with the Docker runtime Docker images as openhands user
   test_runtime_oh:
@@ -378,6 +378,8 @@ jobs:
           TEST_IN_CI=true \
           RUN_AS_OPENHANDS=true \
           poetry run pytest -n 7 -raRs --reruns 2 --reruns-delay 5 -s ./tests/runtime --ignore=tests/runtime/test_browsergym_envs.py --durations=10
+        env:
+          DEBUG: "1"
 
   # The two following jobs (named identically) are to check whether all the runtime tests have passed as the
   # "All Runtime Tests Passed" is a required job for PRs to merge

.github/workflows/lint-fix.yml

@@ -74,7 +74,7 @@ jobs:
       - name: Fix python lint issues
         run: |
           # Run all pre-commit hooks and continue even if they modify files (exit code 1)
-          pre-commit run --config ./dev_config/python/.pre-commit-config.yaml --files openhands/**/* evaluation/**/* tests/**/* || true
+          pre-commit run --config ./dev_config/python/.pre-commit-config.yaml --all-files || true
 
       # Commit and push changes if any
       - name: Check for changes

.github/workflows/lint.yml

@@ -53,7 +53,7 @@ jobs:
       - name: Install pre-commit
         run: pip install pre-commit==3.7.0
       - name: Run pre-commit hooks
-        run: pre-commit run --files openhands/**/* evaluation/**/* tests/**/* --show-diff-on-failure --config ./dev_config/python/.pre-commit-config.yaml
+        run: pre-commit run --all-files --show-diff-on-failure --config ./dev_config/python/.pre-commit-config.yaml
 
   # Check version consistency across documentation
   check-version-consistency:

.github/workflows/py-unit-tests.yml

@@ -74,5 +74,10 @@ jobs:
         run: poetry install --with dev,test,runtime
       - name: Run Windows unit tests
         run: poetry run pytest -svv tests/unit/test_windows_bash.py
+        env:
+          DEBUG: "1"
       - name: Run Windows runtime tests with LocalRuntime
         run: $env:TEST_RUNTIME="local"; poetry run pytest -svv tests/runtime/test_bash.py
+        env:
+          TEST_RUNTIME: local
+          DEBUG: "1"

.openhands/microagents/glossary.md

@@ -121,7 +121,7 @@ A specialized prompt that enhances OpenHands with domain-specific knowledge, rep
 A central repository of available microagents and their configurations.
 
 #### Public Microagent
-A general-purpose microagent available to all OpenHands users, triggered by specific keywords.
+A general-purpose microagent available to all OpenHands users, triggered by specific keywords. Located in `microagents/`.
 
 #### Repository Microagent
 A type of microagent that provides repository-specific context and guidelines, stored in the `.openhands/microagents/` directory.

.openhands/microagents/repo.md

@@ -5,6 +5,14 @@ This repository contains the code for OpenHands, an automated AI software engine
 To set up the entire repo, including frontend and backend, run `make build`.
 You don't need to do this unless the user asks you to, or if you're trying to run the entire application.
 
+## Running OpenHands with OpenHands:
+To run the full application to debug issues:
+```bash
+export INSTALL_DOCKER=0
+export RUNTIME=local
+make build && make run FRONTEND_PORT=12000 FRONTEND_HOST=0.0.0.0 BACKEND_HOST=0.0.0.0 &> /tmp/openhands-log.txt &
+```
+
 IMPORTANT: Before making any changes to the codebase, ALWAYS run `make install-pre-commit-hooks` to ensure pre-commit hooks are properly installed.
 
 Before pushing any changes, you MUST ensure that any lint errors or simple test errors have been fixed.
@@ -44,7 +52,13 @@ Frontend:
   - Available variables: VITE_BACKEND_HOST, VITE_USE_TLS, VITE_INSECURE_SKIP_VERIFY, VITE_FRONTEND_PORT
 - Internationalization:
   - Generate i18n declaration file: `npm run make-i18n`
-
+- Data Fetching & Cache Management:
+  - We use TanStack Query (fka React Query) for data fetching and cache management
+  - Data Access Layer: API client methods are located in `frontend/src/api` and should never be called directly from UI components - they must always be wrapped with TanStack Query
+  - Custom hooks are located in `frontend/src/hooks/query/` and `frontend/src/hooks/mutation/`
+  - Query hooks should follow the pattern use[Resource] (e.g., `useConversationMicroagents`)
+  - Mutation hooks should follow the pattern use[Action] (e.g., `useDeleteConversation`)
+  - Architecture rule: UI components → TanStack Query hooks → Data Access Layer (`frontend/src/api`) → API endpoints
 
 ## Template for Github Pull Request
 
@@ -54,6 +68,29 @@ If you are starting a pull request (PR), please follow the template in `.github/
 
 These details may or may not be useful for your current task.
 
+### Microagents
+
+Microagents are specialized prompts that enhance OpenHands with domain-specific knowledge and task-specific workflows. They are Markdown files that can include frontmatter for configuration.
+
+#### Types:
+- **Public Microagents**: Located in `microagents/`, available to all users
+- **Repository Microagents**: Located in `.openhands/microagents/`, specific to this repository
+
+#### Loading Behavior:
+- **Without frontmatter**: Always loaded into LLM context
+- **With triggers in frontmatter**: Only loaded when user's message matches the specified trigger keywords
+
+#### Structure:
+```yaml
+---
+triggers:
+- keyword1
+- keyword2
+---
+# Microagent Content
+Your specialized knowledge and instructions here...
+```
+
 ### Frontend
 
 #### Action Handling:

Development.md

@@ -103,6 +103,29 @@ components or interface enhancements.
   make start-frontend
   ```
 
+### 5. Running OpenHands with OpenHands
+
+You can use OpenHands to develop and improve OpenHands itself! This is a powerful way to leverage AI assistance for contributing to the project.
+
+#### Quick Start
+
+1. **Build and run OpenHands:**
+   ```bash
+   export INSTALL_DOCKER=0
+   export RUNTIME=local
+   make build && make run
+   ```
+
+2. **Access the interface:**
+   - Local development: http://localhost:3001
+   - Remote/cloud environments: Use the appropriate external URL
+
+3. **Configure for external access (if needed):**
+   ```bash
+   # For external access (e.g., cloud environments)
+   make run FRONTEND_PORT=12000 FRONTEND_HOST=0.0.0.0 BACKEND_HOST=0.0.0.0
+   ```
+
 ### 6. LLM Debugging
 
 If you encounter any issues with the Language Model (LM) or you're simply curious, export DEBUG=1 in the environment and restart the backend.
@@ -136,7 +159,7 @@ poetry run pytest ./tests/unit/test_*.py
 To reduce build time (e.g., if no changes were made to the client-runtime component), you can use an existing Docker
 container image by setting the SANDBOX_RUNTIME_CONTAINER_IMAGE environment variable to the desired Docker image.
 
-Example: `export SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.41-nikolaik`
+Example: `export SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.47-nikolaik`
 
 ## Develop inside Docker container
 

Makefile

@@ -12,6 +12,7 @@ DEFAULT_MODEL = "gpt-4o"
 CONFIG_FILE = config.toml
 PRE_COMMIT_CONFIG_PATH = "./dev_config/python/.pre-commit-config.yaml"
 PYTHON_VERSION = 3.12
+KIND_CLUSTER_NAME = "local-hands"
 
 # ANSI color codes
 GREEN=$(shell tput -Txterm setaf 2)
@@ -189,7 +190,7 @@ install-pre-commit-hooks:
 
 lint-backend:
 	@echo "$(YELLOW)Running linters...$(RESET)"
-	@poetry run pre-commit run --files openhands/**/* evaluation/**/* tests/**/* --show-diff-on-failure --config $(PRE_COMMIT_CONFIG_PATH)
+	@poetry run pre-commit run --all-files --show-diff-on-failure --config $(PRE_COMMIT_CONFIG_PATH)
 
 lint-frontend:
 	@echo "$(YELLOW)Running linters for frontend...$(RESET)"
@@ -199,6 +200,40 @@ lint:
 	@$(MAKE) -s lint-frontend
 	@$(MAKE) -s lint-backend
 
+kind:
+	@echo "$(YELLOW)Checking if kind is installed...$(RESET)"
+	@if ! command -v kind > /dev/null; then \
+		echo "$(RED)kind is not installed. Please install kind with `brew install kind` to continue$(RESET)"; \
+		exit 1; \
+	else \
+		echo "$(BLUE)kind $(shell kind version) is already installed.$(RESET)"; \
+	fi
+	@echo "$(YELLOW)Checking if kind cluster '$(KIND_CLUSTER_NAME)' already exists...$(RESET)"
+	@if kind get clusters | grep -q "^$(KIND_CLUSTER_NAME)$$"; then \
+		echo "$(BLUE)Kind cluster '$(KIND_CLUSTER_NAME)' already exists.$(RESET)"; \
+		kubectl config use-context kind-$(KIND_CLUSTER_NAME); \
+	else \
+		echo "$(YELLOW)Creating kind cluster '$(KIND_CLUSTER_NAME)'...$(RESET)"; \
+		kind create cluster --name $(KIND_CLUSTER_NAME) --config kind/cluster.yaml; \
+	fi
+	@echo "$(YELLOW)Checking if mirrord is installed...$(RESET)"
+	@if ! command -v mirrord > /dev/null; then \
+		echo "$(RED)mirrord is not installed. Please install mirrord with `brew install metalbear-co/mirrord/mirrord` to continue$(RESET)"; \
+		exit 1; \
+	else \
+		echo "$(BLUE)mirrord $(shell mirrord --version) is already installed.$(RESET)"; \
+	fi
+	@echo "$(YELLOW)Installing k8s mirrord resources...$(RESET)"
+	@kubectl apply -f kind/manifests
+	@echo "$(GREEN)Mirrord resources installed successfully.$(RESET)"
+	@echo "$(YELLOW)Waiting for Mirrord pod to be ready.$(RESET)"
+	@sleep 5
+	@kubectl wait --for=condition=Available deployment/ubuntu-dev
+	@echo "$(YELLOW)Waiting for Nginx to be ready.$(RESET)"
+	@kubectl -n ingress-nginx wait --for=condition=Available deployment/ingress-nginx-controller
+	@echo "$(YELLOW)Running make run inside of mirrord.$(RESET)"
+	@mirrord exec --target deployment/ubuntu-dev -- make run
+
 test-frontend:
 	@echo "$(YELLOW)Running tests for frontend...$(RESET)"
 	@cd frontend && npm run test
@@ -333,3 +368,4 @@ help:
 
 # Phony targets
 .PHONY: build check-dependencies check-system check-python check-npm check-nodejs check-docker check-poetry install-python-dependencies install-frontend-dependencies install-pre-commit-hooks lint-backend lint-frontend lint test-frontend test build-frontend start-backend start-frontend _run_setup run run-wsl setup-config setup-config-prompts setup-config-basic openhands-cloud-run docker-dev docker-run clean help
+.PHONY: kind

README.md

@@ -11,13 +11,24 @@
   <a href="https://github.com/All-Hands-AI/OpenHands/stargazers"><img src="https://img.shields.io/github/stars/All-Hands-AI/OpenHands?style=for-the-badge&color=blue" alt="Stargazers"></a>
   <a href="https://github.com/All-Hands-AI/OpenHands/blob/main/LICENSE"><img src="https://img.shields.io/github/license/All-Hands-AI/OpenHands?style=for-the-badge&color=blue" alt="MIT License"></a>
   <br/>
-  <a href="https://join.slack.com/t/openhands-ai/shared_invite/zt-34zm4j0gj-Qz5kRHoca8DFCbqXPS~f_A"><img src="https://img.shields.io/badge/Slack-Join%20Us-red?logo=slack&logoColor=white&style=for-the-badge" alt="Join our Slack community"></a>
+  <a href="https://join.slack.com/t/openhands-ai/shared_invite/zt-3847of6xi-xuYJIPa6YIPg4ElbDWbtSA"><img src="https://img.shields.io/badge/Slack-Join%20Us-red?logo=slack&logoColor=white&style=for-the-badge" alt="Join our Slack community"></a>
   <a href="https://discord.gg/ESHStjSjD4"><img src="https://img.shields.io/badge/Discord-Join%20Us-purple?logo=discord&logoColor=white&style=for-the-badge" alt="Join our Discord community"></a>
   <a href="https://github.com/All-Hands-AI/OpenHands/blob/main/CREDITS.md"><img src="https://img.shields.io/badge/Project-Credits-blue?style=for-the-badge&color=FFE165&logo=github&logoColor=white" alt="Credits"></a>
   <br/>
   <a href="https://docs.all-hands.dev/usage/getting-started"><img src="https://img.shields.io/badge/Documentation-000?logo=googledocs&logoColor=FFE165&style=for-the-badge" alt="Check out the documentation"></a>
   <a href="https://arxiv.org/abs/2407.16741"><img src="https://img.shields.io/badge/Paper%20on%20Arxiv-000?logoColor=FFE165&logo=arxiv&style=for-the-badge" alt="Paper on Arxiv"></a>
   <a href="https://docs.google.com/spreadsheets/d/1wOUdFCMyY6Nt0AIqF705KN4JKOWgeI4wUGUP60krXXs/edit?gid=0#gid=0"><img src="https://img.shields.io/badge/Benchmark%20score-000?logoColor=FFE165&logo=huggingface&style=for-the-badge" alt="Evaluation Benchmark Score"></a>
+
+  <!-- Keep these links. Translations will automatically update with the README. -->
+  <a href="https://www.readme-i18n.com/All-Hands-AI/OpenHands?lang=de">Deutsch</a> |
+  <a href="https://www.readme-i18n.com/All-Hands-AI/OpenHands?lang=es">Español</a> |
+  <a href="https://www.readme-i18n.com/All-Hands-AI/OpenHands?lang=fr">français</a> |
+  <a href="https://www.readme-i18n.com/All-Hands-AI/OpenHands?lang=ja">日本語</a> |
+  <a href="https://www.readme-i18n.com/All-Hands-AI/OpenHands?lang=ko">한국어</a> |
+  <a href="https://www.readme-i18n.com/All-Hands-AI/OpenHands?lang=pt">Português</a> |
+  <a href="https://www.readme-i18n.com/All-Hands-AI/OpenHands?lang=ru">Русский</a> |
+  <a href="https://www.readme-i18n.com/All-Hands-AI/OpenHands?lang=zh">中文</a>
+
   <hr>
 </div>
 
@@ -37,7 +48,7 @@ Learn more at [docs.all-hands.dev](https://docs.all-hands.dev), or [sign up for
 
 ## ☁️ OpenHands Cloud
 The easiest way to get started with OpenHands is on [OpenHands Cloud](https://app.all-hands.dev),
-which comes with $50 in free credits for new users.
+which comes with $20 in free credits for new users.
 
 ## 💻 Running OpenHands Locally
 
@@ -51,19 +62,21 @@ system requirements and more information.
 
 
 ```bash
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
     -e LOG_ALL_EVENTS=true \
     -v /var/run/docker.sock:/var/run/docker.sock \
-    -v ~/.openhands-state:/.openhands-state \
+    -v ~/.openhands:/.openhands \
     -p 3000:3000 \
     --add-host host.docker.internal:host-gateway \
     --name openhands-app \
-    docker.all-hands.dev/all-hands-ai/openhands:0.41
+    docker.all-hands.dev/all-hands-ai/openhands:0.47
 ```
 
+> **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.
+
 You'll find OpenHands running at [http://localhost:3000](http://localhost:3000)!
 
 When you open the application, you'll be asked to choose an LLM provider and add an API key.
@@ -72,15 +85,14 @@ works best, but you have [many options](https://docs.all-hands.dev/usage/llms).
 
 ## 💡 Other ways to run OpenHands
 
-> [!CAUTION]
+> [!WARNING]
 > OpenHands is meant to be run by a single user on their local workstation.
 > It is not appropriate for multi-tenant deployments where multiple users share the same instance. There is no built-in authentication, isolation, or scalability.
 >
-> If you're interested in running OpenHands in a multi-tenant environment, please
-> [get in touch with us](https://docs.google.com/forms/d/e/1FAIpQLSet3VbGaz8z32gW9Wm-Grl4jpt5WgMXPgJ4EDPVmCETCBpJtQ/viewform)
-> for advanced deployment options.
+> If you're interested in running OpenHands in a multi-tenant environment, check out the source-available, commercially-licensed
+> [OpenHands Cloud Helm Chart](https://github.com/all-Hands-AI/OpenHands-cloud)
 
-You can also [connect OpenHands to your local filesystem](https://docs.all-hands.dev/usage/runtimes/docker#connecting-to-your-filesystem),
+You can [connect OpenHands to your local filesystem](https://docs.all-hands.dev/usage/runtimes/docker#connecting-to-your-filesystem),
 run OpenHands in a scriptable [headless mode](https://docs.all-hands.dev/usage/how-to/headless-mode),
 interact with it via a [friendly CLI](https://docs.all-hands.dev/usage/how-to/cli-mode),
 or run it on tagged issues with [a github action](https://docs.all-hands.dev/usage/how-to/github-action).
@@ -105,7 +117,7 @@ troubleshooting resources, and advanced configuration options.
 OpenHands is a community-driven project, and we welcome contributions from everyone. We do most of our communication
 through Slack, so this is the best place to start, but we also are happy to have you contact us on Discord or Github:
 
-- [Join our Slack workspace](https://join.slack.com/t/openhands-ai/shared_invite/zt-34zm4j0gj-Qz5kRHoca8DFCbqXPS~f_A) - Here we talk about research, architecture, and future development.
+- [Join our Slack workspace](https://join.slack.com/t/openhands-ai/shared_invite/zt-3847of6xi-xuYJIPa6YIPg4ElbDWbtSA) - Here we talk about research, architecture, and future development.
 - [Join our Discord server](https://discord.gg/ESHStjSjD4) - This is a community-run server for general discussion, questions, and feedback.
 - [Read or post Github Issues](https://github.com/All-Hands-AI/OpenHands/issues) - Check out the issues we're working on, or add your own ideas.
 
@@ -134,13 +146,12 @@ For a list of open source projects and licenses used in OpenHands, please see ou
 ## 📚 Cite
 
 ```
-@misc{openhands,
-      title={{OpenHands: An Open Platform for AI Software Developers as Generalist Agents}},
-      author={Xingyao Wang and Boxuan Li and Yufan Song and Frank F. Xu and Xiangru Tang and Mingchen Zhuge and Jiayi Pan and Yueqi Song and Bowen Li and Jaskirat Singh and Hoang H. Tran and Fuqiang Li and Ren Ma and Mingzhang Zheng and Bill Qian and Yanjun Shao and Niklas Muennighoff and Yizhe Zhang and Binyuan Hui and Junyang Lin and Robert Brennan and Hao Peng and Heng Ji and Graham Neubig},
-      year={2024},
-      eprint={2407.16741},
-      archivePrefix={arXiv},
-      primaryClass={cs.SE},
-      url={https://arxiv.org/abs/2407.16741},
+@inproceedings{
+  wang2025openhands,
+  title={OpenHands: An Open Platform for {AI} Software Developers as Generalist Agents},
+  author={Xingyao Wang and Boxuan Li and Yufan Song and Frank F. Xu and Xiangru Tang and Mingchen Zhuge and Jiayi Pan and Yueqi Song and Bowen Li and Jaskirat Singh and Hoang H. Tran and Fuqiang Li and Ren Ma and Mingzhang Zheng and Bill Qian and Yanjun Shao and Niklas Muennighoff and Yizhe Zhang and Binyuan Hui and Junyang Lin and Robert Brennan and Hao Peng and Heng Ji and Graham Neubig},
+  booktitle={The Thirteenth International Conference on Learning Representations},
+  year={2025},
+  url={https://openreview.net/forum?id=OJd3ayDDoF}
 }
 ```

README_CN.md

@@ -12,7 +12,7 @@
   <a href="https://github.com/All-Hands-AI/OpenHands/stargazers"><img src="https://img.shields.io/github/stars/All-Hands-AI/OpenHands?style=for-the-badge&color=blue" alt="Stargazers"></a>
   <a href="https://github.com/All-Hands-AI/OpenHands/blob/main/LICENSE"><img src="https://img.shields.io/github/license/All-Hands-AI/OpenHands?style=for-the-badge&color=blue" alt="MIT License"></a>
   <br/>
-  <a href="https://join.slack.com/t/openhands-ai/shared_invite/zt-34zm4j0gj-Qz5kRHoca8DFCbqXPS~f_A"><img src="https://img.shields.io/badge/Slack-Join%20Us-red?logo=slack&logoColor=white&style=for-the-badge" alt="加入我们的Slack社区"></a>
+  <a href="https://join.slack.com/t/openhands-ai/shared_invite/zt-3847of6xi-xuYJIPa6YIPg4ElbDWbtSA"><img src="https://img.shields.io/badge/Slack-Join%20Us-red?logo=slack&logoColor=white&style=for-the-badge" alt="加入我们的Slack社区"></a>
   <a href="https://discord.gg/ESHStjSjD4"><img src="https://img.shields.io/badge/Discord-Join%20Us-purple?logo=discord&logoColor=white&style=for-the-badge" alt="加入我们的Discord社区"></a>
   <a href="https://github.com/All-Hands-AI/OpenHands/blob/main/CREDITS.md"><img src="https://img.shields.io/badge/Project-Credits-blue?style=for-the-badge&color=FFE165&logo=github&logoColor=white" alt="致谢"></a>
   <br/>
@@ -51,19 +51,21 @@ OpenHands也可以使用Docker在本地系统上运行。
 
 
 ```bash
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
     -e LOG_ALL_EVENTS=true \
     -v /var/run/docker.sock:/var/run/docker.sock \
-    -v ~/.openhands-state:/.openhands-state \
+    -v ~/.openhands:/.openhands \
     -p 3000:3000 \
     --add-host host.docker.internal:host-gateway \
     --name openhands-app \
-    docker.all-hands.dev/all-hands-ai/openhands:0.41
+    docker.all-hands.dev/all-hands-ai/openhands:0.47
 ```
 
+> **注意**: 如果您在0.44版本之前使用过OpenHands，您可能需要运行 `mv ~/.openhands-state ~/.openhands` 来将对话历史迁移到新位置。
+
 您将在[http://localhost:3000](http://localhost:3000)找到运行中的OpenHands！
 
 打开应用程序时，您将被要求选择一个LLM提供商并添加API密钥。
@@ -105,7 +107,7 @@ docker run -it --rm --pull=always \
 OpenHands是一个社区驱动的项目，我们欢迎每个人的贡献。我们大部分沟通
 通过Slack进行，因此这是开始的最佳场所，但我们也很乐意您通过Discord或Github与我们联系：
 
-- [加入我们的Slack工作空间](https://join.slack.com/t/openhands-ai/shared_invite/zt-34zm4j0gj-Qz5kRHoca8DFCbqXPS~f_A) - 这里我们讨论研究、架构和未来发展。
+- [加入我们的Slack工作空间](https://join.slack.com/t/openhands-ai/shared_invite/zt-3847of6xi-xuYJIPa6YIPg4ElbDWbtSA) - 这里我们讨论研究、架构和未来发展。
 - [加入我们的Discord服务器](https://discord.gg/ESHStjSjD4) - 这是一个社区运营的服务器，用于一般讨论、问题和反馈。
 - [阅读或发布Github问题](https://github.com/All-Hands-AI/OpenHands/issues) - 查看我们正在处理的问题，或添加您自己的想法。
 

README_JA.md

@@ -0,0 +1,60 @@
+<a name="readme-top"></a>
+
+<div align="center">
+  <img src="./docs/static/img/logo.png" alt="Logo" width="200">
+  <h1 align="center">OpenHands: コードを減らして、もっと作ろう</h1>
+</div>
+
+<div align="center">
+  <a href="https://github.com/All-Hands-AI/OpenHands/graphs/contributors"><img src="https://img.shields.io/github/contributors/All-Hands-AI/OpenHands?style=for-the-badge&color=blue" alt="Contributors"></a>
+  <a href="https://github.com/All-Hands-AI/OpenHands/stargazers"><img src="https://img.shields.io/github/stars/All-Hands-AI/OpenHands?style=for-the-badge&color=blue" alt="Stargazers"></a>
+  <a href="https://github.com/All-Hands-AI/OpenHands/blob/main/LICENSE"><img src="https://img.shields.io/github/license/All-Hands-AI/OpenHands?style=for-the-badge&color=blue" alt="MIT License"></a>
+  <br/>
+  <a href="https://join.slack.com/t/openhands-ai/shared_invite/zt-3847of6xi-xuYJIPa6YIPg4ElbDWbtSA"><img src="https://img.shields.io/badge/Slack-Join%20Us-red?logo=slack&logoColor=white&style=for-the-badge" alt="Slackコミュニティに参加"></a>
+  <a href="https://discord.gg/ESHStjSjD4"><img src="https://img.shields.io/badge/Discord-Join%20Us-purple?logo=discord&logoColor=white&style=for-the-badge" alt="Discordコミュニティに参加"></a>
+  <a href="https://github.com/All-Hands-AI/OpenHands/blob/main/CREDITS.md"><img src="https://img.shields.io/badge/Project-Credits-blue?style=for-the-badge&color=FFE165&logo=github&logoColor=white" alt="クレジット"></a>
+  <br/>
+  <a href="https://docs.all-hands.dev/usage/getting-started"><img src="https://img.shields.io/badge/Documentation-000?logo=googledocs&logoColor=FFE165&style=for-the-badge" alt="ドキュメントを見る"></a>
+  <a href="https://arxiv.org/abs/2407.16741"><img src="https://img.shields.io/badge/Paper%20on%20Arxiv-000?logoColor=FFE165&logo=arxiv&style=for-the-badge" alt="Arxiv論文"></a>
+  <a href="https://docs.google.com/spreadsheets/d/1wOUdFCMyY6Nt0AIqF705KN4JKOWgeI4wUGUP60krXXs/edit?gid=0#gid=0"><img src="https://img.shields.io/badge/Benchmark%20score-000?logoColor=FFE165&logo=huggingface&style=for-the-badge" alt="評価ベンチマークスコア"></a>
+  <hr>
+</div>
+
+OpenHands（旧OpenDevin）へようこそ。これはAIが駆動するソフトウェア開発エージェントのプラットフォームです。
+
+OpenHandsのエージェントは人間の開発者ができることは何でもこなします。コードを修正し、コマンドを実行し、ウェブを閲覧し、APIを呼び出し、StackOverflowからコードスニペットをコピーすることさえできます。
+
+詳細は[docs.all-hands.dev](https://docs.all-hands.dev)をご覧いただくか、[OpenHands Cloud](https://app.all-hands.dev)に登録して始めましょう。
+
+> [!IMPORTANT]
+> 仕事でOpenHandsを使っていますか？ぜひお話を聞かせてください。[こちらの短いフォーム](https://docs.google.com/forms/d/e/1FAIpQLSet3VbGaz8z32gW9Wm-Grl4jpt5WgMXPgJ4EDPVmCETCBpJtQ/viewform)にご記入いただき、Design Partnerプログラムにご参加ください。商用機能の早期アクセスや製品ロードマップへのフィードバックの機会を提供します。
+
+![アプリのスクリーンショット](./docs/static/img/screenshot.png)
+
+## ☁️ OpenHands Cloud
+OpenHandsを始める最も簡単な方法は[OpenHands Cloud](https://app.all-hands.dev)を利用することです。新規ユーザーには50ドル分の無料クレジットが付与されます。
+
+## 💻 OpenHandsをローカルで実行する
+
+OpenHandsはDockerを利用してローカル環境でも実行できます。システム要件や詳細については[Running OpenHands](https://docs.all-hands.dev/usage/installation)ガイドをご覧ください。
+
+> [!WARNING]
+> 公共ネットワークで実行していますか？[Hardened Docker Installation Guide](https://docs.all-hands.dev/usage/runtimes/docker#hardened-docker-installation)を参照して、ネットワークバインディングの制限や追加のセキュリティ対策を実施してください。
+
+```bash
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik
+
+docker run -it --rm --pull=always \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
+    -e LOG_ALL_EVENTS=true \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -v ~/.openhands:/.openhands \
+    -p 3000:3000 \
+    --add-host host.docker.internal:host-gateway \
+    --name openhands-app \
+    docker.all-hands.dev/all-hands-ai/openhands:0.47
+```
+
+**注**: バージョン0.44以前のOpenHandsを使用していた場合は、会話履歴を移行するために `mv ~/.openhands-state ~/.openhands` を実行してください。
+
+OpenHandsは[http://localhost:3000](http://localhost:3000)で起動します！

config.template.toml

@@ -10,18 +10,7 @@
 # General core configurations
 ##############################################################################
 [core]
-# API key for E2B
-#e2b_api_key = ""
-
-# API key for Modal
-#modal_api_token_id = ""
-#modal_api_token_secret = ""
-
-# API key for Daytona
-#daytona_api_key = ""
-
-# Daytona Target
-#daytona_target = ""
+# API keys and configuration for core services
 
 # Base path for the workspace
 #workspace_base = "./workspace"
@@ -64,7 +53,7 @@
 #max_budget_per_task = 0.0
 
 # Maximum number of iterations
-#max_iterations = 250
+#max_iterations = 500
 
 # Path to mount the workspace in the sandbox
 #workspace_mount_path_in_sandbox = "/workspace"
@@ -201,6 +190,27 @@ model = "gpt-4o"
 #native_tool_calling = None
 
 
+# Safety settings for models that support them (e.g., Mistral AI, Gemini)
+# Example for Mistral AI:
+# safety_settings = [
+#   { "category" = "hate", "threshold" = "low" },
+#   { "category" = "harassment", "threshold" = "low" },
+#   { "category" = "sexual", "threshold" = "low" },
+#   { "category" = "dangerous", "threshold" = "low" }
+# ]
+#
+# Example for Gemini:
+# safety_settings = [
+#   { "category" = "HARM_CATEGORY_HARASSMENT", "threshold" = "BLOCK_NONE" },
+#   { "category" = "HARM_CATEGORY_HATE_SPEECH", "threshold" = "BLOCK_NONE" },
+#   { "category" = "HARM_CATEGORY_SEXUALLY_EXPLICIT", "threshold" = "BLOCK_NONE" },
+#   { "category" = "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold" = "BLOCK_NONE" }
+# ]
+#safety_settings = []
+
+[llm.draft_editor]
+# The number of times llm_editor tries to fix an error when editing.
+correct_num = 5
 
 [llm.gpt4o-mini]
 api_key = ""
@@ -250,6 +260,9 @@ enable_finish = true
 # length limit
 enable_history_truncation = true
 
+# Whether the condensation request tool is enabled
+enable_condensation_request = false
+
 [agent.RepoExplorerAgent]
 # Example: use a cheaper model for RepoExplorerAgent to reduce cost, especially
 # useful when an agent doesn't demand high quality but uses a lot of tokens
@@ -318,6 +331,9 @@ classpath = "my_package.my_module.MyCustomAgent"
 # Enable GPU support in the runtime
 #enable_gpu = false
 
+# When there are multiple cards, you can specify the GPU by ID
+#cuda_visible_devices = ''
+
 # Additional Docker runtime kwargs
 #docker_runtime_kwargs = {}
 
@@ -415,3 +431,47 @@ type = "noop"
 # Configuration for the evaluation, please refer to the specific evaluation
 # plugin for the available options
 ##############################################################################
+
+
+########################### Kubernetes #######################################
+# Kubernetes configuration when using the Kubernetes runtime
+##############################################################################
+[kubernetes]
+# The Kubernetes namespace to use for OpenHands resources
+#namespace = "default"
+
+# Domain for ingress resources
+#ingress_domain = "localhost"
+
+# Size of the persistent volume claim
+#pvc_storage_size = "2Gi"
+
+# Storage class for persistent volume claims
+#pvc_storage_class = "standard"
+
+# CPU request for runtime pods
+#resource_cpu_request = "1"
+
+# Memory request for runtime pods
+#resource_memory_request = "1Gi"
+
+# Memory limit for runtime pods
+#resource_memory_limit = "2Gi"
+
+# Optional name of image pull secret for private registries
+#image_pull_secret = ""
+
+# Optional name of TLS secret for ingress
+#ingress_tls_secret = ""
+
+# Optional node selector key for pod scheduling
+#node_selector_key = ""
+
+# Optional node selector value for pod scheduling
+#node_selector_val = ""
+
+# Optional YAML string defining pod tolerations
+#tolerations_yaml = ""
+
+# Run the runtime sandbox container in privileged mode for use with docker-in-docker
+#privileged = false

containers/app/Dockerfile

@@ -1,16 +1,16 @@
 ARG OPENHANDS_BUILD_VERSION=dev
-FROM node:21.7.2-bookworm-slim AS frontend-builder
+FROM node:24.3.0-bookworm-slim AS frontend-builder
 
 WORKDIR /app
 
-COPY ./frontend/package.json frontend/package-lock.json ./
-RUN npm install -g npm@10.5.1
+COPY frontend/package.json frontend/package-lock.json ./
 RUN npm ci
 
-COPY ./frontend ./
+COPY frontend ./
 RUN npm run build
 
-FROM python:3.12.3-slim AS backend-builder
+FROM python:3.12.10-slim AS base
+FROM base AS backend-builder
 
 WORKDIR /app
 ENV PYTHONPATH='/app'
@@ -22,17 +22,18 @@ ENV POETRY_NO_INTERACTION=1 \
 
 RUN apt-get update -y \
     && apt-get install -y curl make git build-essential \
-    && python3 -m pip install poetry==1.8.2  --break-system-packages
+    && python3 -m pip install poetry --break-system-packages
 
-COPY ./pyproject.toml ./poetry.lock ./
+COPY pyproject.toml poetry.lock ./
 RUN touch README.md
 RUN export POETRY_CACHE_DIR && poetry install --no-root && rm -rf $POETRY_CACHE_DIR
 
-FROM python:3.12.3-slim AS openhands-app
+FROM base AS openhands-app
 
 WORKDIR /app
 
-ARG OPENHANDS_BUILD_VERSION #re-declare for this section
+# re-declare for this section
+ARG OPENHANDS_BUILD_VERSION
 
 ENV RUN_AS_OPENHANDS=true
 # A random number--we need this to be different from the user's UID on the host machine
@@ -43,7 +44,7 @@ ENV WORKSPACE_BASE=/opt/workspace_base
 ENV OPENHANDS_BUILD_VERSION=$OPENHANDS_BUILD_VERSION
 ENV SANDBOX_USER_ID=0
 ENV FILE_STORE=local
-ENV FILE_STORE_PATH=/.openhands-state
+ENV FILE_STORE_PATH=/.openhands
 RUN mkdir -p $FILE_STORE_PATH
 RUN mkdir -p $WORKSPACE_BASE
 
@@ -74,12 +75,7 @@ COPY --chown=openhands:app --chmod=770 --from=backend-builder ${VIRTUAL_ENV} ${V
 COPY --chown=openhands:app --chmod=770 ./microagents ./microagents
 COPY --chown=openhands:app --chmod=770 ./openhands ./openhands
 COPY --chown=openhands:app --chmod=777 ./openhands/runtime/plugins ./openhands/runtime/plugins
-COPY --chown=openhands:app --chmod=770 ./openhands/agenthub ./openhands/agenthub
-COPY --chown=openhands:app ./pyproject.toml ./pyproject.toml
-COPY --chown=openhands:app ./poetry.lock ./poetry.lock
-COPY --chown=openhands:app ./README.md ./README.md
-COPY --chown=openhands:app ./MANIFEST.in ./MANIFEST.in
-COPY --chown=openhands:app ./LICENSE ./LICENSE
+COPY --chown=openhands:app pyproject.toml poetry.lock README.md MANIFEST.in LICENSE ./
 
 # This is run as "openhands" user, and will create __pycache__ with openhands:openhands ownership
 RUN python openhands/core/download.py # No-op to download assets

containers/dev/compose.yml

@@ -10,8 +10,9 @@ services:
     environment:
       - BACKEND_HOST=${BACKEND_HOST:-"0.0.0.0"}
       - SANDBOX_API_HOSTNAME=host.docker.internal
+      - DOCKER_HOST_ADDR=host.docker.internal
       #
-      - SANDBOX_RUNTIME_CONTAINER_IMAGE=${SANDBOX_RUNTIME_CONTAINER_IMAGE:-ghcr.io/all-hands-ai/runtime:0.41-nikolaik}
+      - SANDBOX_RUNTIME_CONTAINER_IMAGE=${SANDBOX_RUNTIME_CONTAINER_IMAGE:-ghcr.io/all-hands-ai/runtime:0.47-nikolaik}
       - SANDBOX_USER_ID=${SANDBOX_USER_ID:-1234}
       - WORKSPACE_MOUNT_PATH=${WORKSPACE_BASE:-$PWD/workspace}
     ports:

dev_config/python/.pre-commit-config.yaml

@@ -3,10 +3,11 @@ repos:
     rev: v5.0.0
     hooks:
       - id: trailing-whitespace
-        exclude: docs/modules/python
+        exclude: ^(docs/|modules/|python/|openhands-ui/|third_party/)
       - id: end-of-file-fixer
-        exclude: docs/modules/python
+        exclude: ^(docs/|modules/|python/|openhands-ui/|third_party/)
       - id: check-yaml
+        args: ["--allow-multiple-documents"]
       - id: debug-statements
 
   - repo: https://github.com/tox-dev/pyproject-fmt
@@ -27,17 +28,19 @@ repos:
         entry: ruff check --config dev_config/python/ruff.toml
         types_or: [python, pyi, jupyter]
         args: [--fix, --unsafe-fixes]
+        exclude: third_party/
       # Run the formatter.
       - id: ruff-format
         entry: ruff format --config dev_config/python/ruff.toml
         types_or: [python, pyi, jupyter]
+        exclude: third_party/
 
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.15.0
     hooks:
       - id: mypy
         additional_dependencies:
-          [types-requests, types-setuptools, types-pyyaml, types-toml, types-docker, lxml]
+          [types-requests, types-setuptools, types-pyyaml, types-toml, types-docker, pydantic, lxml]
         # To see gaps add `--html-report mypy-report/`
         entry: mypy --config-file dev_config/python/mypy.ini openhands/
         always_run: true

dev_config/python/mypy.ini

@@ -7,3 +7,9 @@ warn_unreachable = True
 warn_redundant_casts = True
 no_implicit_optional = True
 strict_optional = True
+
+# Exclude third-party runtime directory from type checking
+exclude = third_party/
+
+[mypy-openhands.memory.condenser.impl.*]
+disable_error_code = override

dev_config/python/ruff.toml

@@ -1,3 +1,6 @@
+# Exclude third-party runtime directory from linting
+exclude = ["third_party/"]
+
 [lint]
 select = [
     "E",

docker-compose.yml

@@ -7,8 +7,8 @@ services:
     image: openhands:latest
     container_name: openhands-app-${DATE:-}
     environment:
-      - SANDBOX_RUNTIME_CONTAINER_IMAGE=${SANDBOX_RUNTIME_CONTAINER_IMAGE:-docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik}
-      #- SANDBOX_USER_ID=${SANDBOX_USER_ID:-1234} # enable this only if you want a specific non-root sandbox user but you will have to manually adjust permissions of openhands-state for this user
+      - SANDBOX_RUNTIME_CONTAINER_IMAGE=${SANDBOX_RUNTIME_CONTAINER_IMAGE:-docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik}
+      #- SANDBOX_USER_ID=${SANDBOX_USER_ID:-1234} # enable this only if you want a specific non-root sandbox user but you will have to manually adjust permissions of ~/.openhands for this user
       - WORKSPACE_MOUNT_PATH=${WORKSPACE_BASE:-$PWD/workspace}
     ports:
       - "3000:3000"
@@ -16,7 +16,7 @@ services:
       - "host.docker.internal:host-gateway"
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
-      - ~/.openhands-state:/.openhands-state
+      - ~/.openhands:/.openhands
       - ${WORKSPACE_BASE:-$PWD/workspace}:/opt/workspace_base
     pull_policy: build
     stdin_open: true

docs/README.md

@@ -0,0 +1,17 @@
+# Setup
+
+```
+npm install -g mint
+```
+
+or
+
+```
+yarn global add mint
+```
+
+# Preview
+
+```
+mint dev
+```

docs/README_JA.md

@@ -0,0 +1,17 @@
+# セットアップ
+
+```
+npm install -g mint
+```
+
+または
+
+```
+yarn global add mint
+```
+
+# プレビュー
+
+```
+mint dev
+```

docs/docs.json

@@ -26,6 +26,7 @@
           "usage/installation",
           "usage/getting-started",
           "usage/key-features",
+          "usage/faqs",
           {
             "group": "OpenHands Cloud",
             "pages": [
@@ -34,28 +35,78 @@
                 "group": "Integrations",
                 "pages": [
                   "usage/cloud/github-installation",
-                  "usage/cloud/gitlab-installation"
+                  "usage/cloud/gitlab-installation",
+                  "usage/cloud/slack-installation"
                 ]
               },
               "usage/cloud/cloud-ui",
-              "usage/cloud/cloud-issue-resolver",
               "usage/cloud/cloud-api"
             ]
           },
           {
-            "group": "Running OpenHands Locally",
+            "group": "Run OpenHands on Your Own",
             "pages": [
               "usage/local-setup",
               "usage/how-to/gui-mode",
               "usage/how-to/cli-mode",
               "usage/how-to/headless-mode",
-              "usage/how-to/github-action"
+              "usage/how-to/github-action",
+              {
+                "group": "Advanced Configuration",
+                "pages": [
+                {
+                  "group": "LLM Configuration",
+                  "pages": [
+                    "usage/llms/llms",
+                    {
+                      "group": "Providers",
+                      "pages": [
+                        "usage/llms/azure-llms",
+                        "usage/llms/google-llms",
+                        "usage/llms/groq",
+                        "usage/llms/local-llms",
+                        "usage/llms/litellm-proxy",
+                        "usage/llms/openai-llms",
+                        "usage/llms/openrouter"
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "group": "Runtime Configuration",
+                  "pages": [
+                    "usage/runtimes/overview",
+                    {
+                      "group": "Providers",
+                      "pages": [
+                        "usage/runtimes/docker",
+                        "usage/runtimes/remote",
+                        "usage/runtimes/local",
+                        {
+                          "group": "Third-Party Providers",
+                          "pages": [
+                            "usage/runtimes/modal",
+                            "usage/runtimes/daytona",
+                            "usage/runtimes/runloop",
+                            "usage/runtimes/e2b"
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                },
+                "usage/configuration-options",
+                "usage/how-to/custom-sandbox-guide",
+                "usage/search-engine-setup",
+                "usage/mcp"
+                ]
+              }
             ]
           },
           {
-            "group": "Customization",
+            "group": "Customizations & Settings",
             "pages": [
-              "usage/prompting/prompting-best-practices",
+              "usage/common-settings",
               "usage/prompting/repository",
               {
                 "group": "Microagents",
@@ -70,53 +121,9 @@
             ]
           },
           {
-            "group": "Advanced Configuration",
+            "group": "Tips and Tricks",
             "pages": [
-            {
-              "group": "LLM Configuration",
-              "pages": [
-                "usage/llms/llms",
-                {
-                  "group": "Providers",
-                  "pages": [
-                    "usage/llms/azure-llms",
-                    "usage/llms/google-llms",
-                    "usage/llms/groq",
-                    "usage/llms/local-llms",
-                    "usage/llms/litellm-proxy",
-                    "usage/llms/openai-llms",
-                    "usage/llms/openrouter"
-                  ]
-                }
-              ]
-            },
-            {
-              "group": "Runtime Configuration",
-              "pages": [
-                "usage/runtimes/overview",
-                {
-                  "group": "Providers",
-                  "pages": [
-                    "usage/runtimes/docker",
-                    "usage/runtimes/remote",
-                    "usage/runtimes/local",
-                    {
-                      "group": "Third-Party Providers",
-                      "pages": [
-                        "usage/runtimes/modal",
-                        "usage/runtimes/daytona",
-                        "usage/runtimes/runloop",
-                        "usage/runtimes/e2b"
-                      ]
-                    }
-                  ]
-                }
-              ]
-            },
-            "usage/configuration-options",
-            "usage/how-to/custom-sandbox-guide",
-            "usage/search-engine-setup",
-            "usage/mcp"
+              "usage/prompting/prompting-best-practices"
             ]
           },
           {
@@ -144,6 +151,12 @@
           }
         ]
       },
+      {
+        "tab": "Success Stories",
+        "pages": [
+          "success-stories/index"
+        ]
+      },
       {
           "tab": "API Reference",
           "openapi": "/openapi.json"
@@ -183,7 +196,7 @@
   },
   "footer": {
     "socials": {
-      "slack": "https://join.slack.com/t/openhands-ai/shared_invite/zt-34zm4j0gj-Qz5kRHoca8DFCbqXPS~f_A",
+      "slack": "https://join.slack.com/t/openhands-ai/shared_invite/zt-3847of6xi-xuYJIPa6YIPg4ElbDWbtSA",
       "github": "https://github.com/All-Hands-AI/OpenHands",
       "discord": "https://discord.gg/ESHStjSjD4"
     }

docs/success-stories/index.mdx

@@ -0,0 +1,217 @@
+---
+title: "Success Stories"
+description: "Real-world examples of what you can achieve with OpenHands"
+---
+
+Discover how developers and teams are using OpenHands to automate their software development workflows. From quick fixes to complex projects, see what's possible with AI-powered development assistance.
+
+Check out the [#success-stories](https://www.linen.dev/s/openhands/c/success-stories) channel on our Slack for more!
+
+<Update label="2025-06-13 OpenHands helps frontline support" description="@Joe Pelletier">
+
+## One of the cool things about OpenHands, and especially the Slack Integration, is the ability to empower folks who are on the ‘front lines’ with customers.
+
+For example, often times Support and Customer Success teams will field bug reports, doc questions, and other ‘nits’ from customers. They tend to have few options to deal with this, other than file a feedback ticket with product teams and hope it gets prioritized in an upcoming sprint.
+
+Instead, with tools like OpenHands and the Slack integration, they can request OpenHands to make fixes proactively and then have someone on the engineering team (like a lead engineer, a merge engineer, or even technical product manager) review the PR and approve it — thus reducing the cycle time for ‘quick wins’ from weeks to just a few hours.
+
+Here's how we do that with the OpenHands project:
+
+<iframe
+  width="560"
+  height="560"
+  src="https://www.linen.dev/s/openhands/t/29118545/seems-mcp-config-from-config-toml-is-being-overwritten-hence#629f8e2b-cde8-427e-920c-390557a06cc9"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
+
+[Original Slack thread](https://www.linen.dev/s/openhands/t/29124350/one-of-the-cool-things-about-openhands-and-especially-the-sl#25029f37-7b0d-4535-9187-83b3e06a4011)
+
+</Update>
+
+
+<Update label="2025-06-13 Ask OpenHands to show me some love" description="@Graham Neubig">
+
+## Asked openhands to “show me some love” and...
+
+Asked openhands to “show me some love” and it coded up this app for me, actually kinda genuinely feel loved
+
+<video
+  controls
+  autoplay
+  className="w-full aspect-video"
+  src="/success-stories/stories/2025-06-13-show-love/v1.mp4"
+></video>
+
+[Original Slack thread](https://www.linen.dev/s/openhands/t/29100731/asked-openhands-to-show-me-some-love-and-it-coded-up-this-ap#1e08af6b-b7d5-4167-8a53-17e6806555e0)
+
+</Update>
+
+<Update label="2025-06-11 OpenHands does 100% of my infra IAM research for me" description="@Xingyao Wang">
+
+## Now, OpenHands does 100% of my infra IAM research for me
+
+Got an IAM error on GCP? Send a screenshot to OH... and it just works!!!
+Can't imagine going back to the early days without OH: I'd spend an entire afternoon figuring how to get IAM right
+
+[Original Slack thread](https://www.linen.dev/s/openhands/t/29100732/now-openhands-does-100-of-my-infra-iam-research-for-me-sweat#20482a73-4e2e-4edd-b6d1-c9e8442fccd1)
+
+![](/success-stories/stories/2025-06-11-infra-iam/s1.png)
+![](/success-stories/stories/2025-06-11-infra-iam/s2.png)
+
+</Update>
+
+<Update label="2025-06-08 OpenHands builds an interactive map for me" description="@Rodrigo Argenton Freire (ODLab)">
+
+## Very simple example, but baby steps....
+
+I am a professor of architecture and urban design. We built, me and some students, an interactive map prototype to help visitors and new students to find important places in the campus. Considering that we lack a lot of knowledge in programming, that was really nice to build and a smooth process.
+We first created the main components with all-hands and then adjusted some details locally. Definitely, saved us a lot of time and money.
+That's a prototype but we will have all the info by tuesday.
+https://buriti-emau.github.io/Mapa-UFU/
+
+[Original Slack thread](https://www.linen.dev/s/openhands/t/29100736/very-simple-example-but-baby-steps-i-am-a-professor-of-archi#8f2e3f3f-44e6-44ea-b9a8-d53487470179)
+
+![](/success-stories/stories/2025-06-08-map/s1.png)
+
+</Update>
+
+
+<Update label="2025-06-06 Web Search Saves the Day" description="@Ian Walker">
+
+## Tavily adapter helps solve persistent debugging issue
+
+Big congratulations to the new [Tavily adapter](https://www.all-hands.dev/blog/building-a-provably-versatile-agent)... OpenHands and I have been beavering away at a Lightstreamer client library for most of this week but were getting a persistent (and unhelpful) "unexpected error" from the server.
+
+Coming back to the problem today, after trying several unsuccessful fixes prompted by me, OH decided all by itself to search the web, and found the cause of the problem (of course it was simply CRLF line endings...). I was on the verge of giving up - good thing OH has more stamina than me!
+
+This demonstrates how OpenHands' web search capabilities can help solve debugging issues that would otherwise require extensive manual research.
+
+<iframe
+  width="560"
+  height="560"
+  src="https://www.linen.dev/s/openhands/t/29100737/big-congratulations-to-the-new-tavily-adapter-openhands-and-#87b027e5-188b-425e-8aa9-719dcb4929f4"
+  title="YouTube video player"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
+
+
+[Original Slack thread](https://www.linen.dev/s/openhands/t/29100737/big-congratulations-to-the-new-tavily-adapter-openhands-and-#76f1fb26-6ef7-4709-b9ea-fb99105e47e4)
+
+</Update>
+
+<Update label="2025-06-05 OpenHands updates my personal website for a new paper" description="@Xingyao Wang">
+
+## I asked OpenHands to update my personal website for the "OpenHands Versa" paper.
+
+It is an extremely trivial task: You just need to browse to arxiv, copy the author names, format them for BibTeX, and then modify the papers.bib file. But now I'm getting way too lazy to even open my IDE and actually do this one-file change!
+
+[Original Tweet/X thread](https://x.com/xingyaow_/status/1930796287919542410)
+
+[Original Slack thread](https://www.linen.dev/s/openhands/t/29100738/i-asked-openhands-to-update-my-personal-website-for-the-open#f0324022-b12b-4d34-b12b-bdbc43823f69)
+
+</Update>
+
+<Update label="2025-06-02 OpenHands makes an animated gif of swe-bench verified scores over time" description="@Graham Neubig">
+
+## I asked OpenHands to make an animated gif of swe-bench verified scores over time.
+
+It took a bit of prompting but ended up looking pretty nice I think
+
+<video width="560" height="315" autoPlay loop muted src="/success-stories/stories/2025-06-02-swebench-score/s1.mp4"></video>
+
+[Original Slack thread](https://www.linen.dev/s/openhands/t/29100744/i-asked-openhands-to-make-an-animated-gif-of-swe-bench-verif#fb3b82c9-6222-4311-b97b-b2ac1cfe6dff)
+
+</Update>
+
+<Update label="2025-05-30 AWS Troubleshooting" description="@Graham Neubig">
+
+## Quick AWS security group fix
+
+I really don't like trying to fix issues with AWS, especially security groups and other finicky things like this. But I started up an instance and wasn't able to ssh in. So I asked OpenHands:
+
+> Currently, the following ssh command is timing out:
+>
+> $ ssh -i gneubig.pem ubuntu@XXX.us-east-2.compute.amazonaws.com
+> ssh: connect to host XXX.us-east-2.compute.amazonaws.com port 22: Operation timed out
+>
+> Use the provided AWS credentials to take a look at i-XXX and examine why
+
+And 2 minutes later I was able to SSH in!
+
+This shows how OpenHands can quickly diagnose and fix AWS infrastructure issues that would normally require manual investigation.
+
+[Original Slack thread](https://www.linen.dev/s/openhands/t/29100747/i-really-don-t-like-trying-to-fix-issues-with-aws-especially#d92a66d2-3bc1-4467-9d09-dc983004d083)
+
+</Update>
+
+
+<Update label="2025-05-04 Chrome Extension Development" description="@Xingyao Wang">
+
+## OpenHands builds Chrome extension for GitHub integration
+
+I asked OpenHands to write a Chrome extension based on our [OpenHands Cloud API](https://docs.all-hands.dev/modules/usage/cloud/cloud-api). Once installed, you can now easily launch an OpenHands cloud session from your GitHub webpage/PR!
+
+This demonstrates OpenHands' ability to create browser extensions and integrate with external APIs, enabling seamless workflows between GitHub and OpenHands Cloud.
+
+![Chrome extension](/success-stories/stories/2025-05-04-chrome-extension/s1.png)
+![Chrome extension](/success-stories/stories/2025-05-04-chrome-extension/s2.png)
+
+[GitHub Repository](https://github.com/xingyaoww/openhands-chrome-extension)
+
+[Original Slack thread](https://www.linen.dev/s/openhands/t/29100755/i-asked-openhands-to-write-a-chrome-extension-based-on-our-h#88f14b7f-f8ff-40a6-83c2-bd64e95924c5)
+
+</Update>
+
+
+<Update label="2025-04-11 Visual UI Testing" description="@Xingyao Wang">
+
+## OpenHands tests UI automatically with visual browsing
+
+Thanks to visual browsing -- OpenHands can actually test some simple UI by serving the website, clicking the button in the browser and looking at screenshots now!
+
+Prompt is just:
+```
+I want to create a Hello World app in Javascript that:
+* Displays Hello World in the middle.
+* Has a button that when clicked, changes the greeting with a bouncing animation to fun versions of Hello.
+* Has a counter for how many times the button has been clicked.
+* Has another button that changes the app's background color.
+```
+
+Eager-to-work Sonnet 3.7 will test stuff for you without you asking!
+
+This showcases OpenHands' visual browsing capabilities, enabling it to create, serve, and automatically test web applications through actual browser interactions and screenshot analysis.
+
+![Visual UI testing](/success-stories/stories/2025-04-11-visual-ui/s1.png)
+
+[Original Slack thread](https://www.linen.dev/s/openhands/t/29100764/thanks-to-u07k0p3bdb9-s-visual-browsing-openhands-can-actual#21beb9bc-1a04-4272-87e9-4d3e3b9925e7)
+
+</Update>
+
+<Update label="2025-03-07 Proactive Error Handling" description="@Graham Neubig">
+
+## OpenHands fixes crashes before you notice them
+
+Interesting story, I asked OpenHands to start an app on port 12000, it showed up on the app pane. I started using the app, and then it crashed... But because it crashed in OpenHands, OpenHands immediately saw the error message and started fixing the problem without me having to do anything. It was already fixing the problem before I even realized what was going wrong.
+
+This demonstrates OpenHands' proactive monitoring capabilities - it doesn't just execute commands, but actively watches for errors and begins remediation automatically, often faster than human reaction time.
+
+</Update>
+
+<Update label="2024-12-03 Creative Design Acceleration" description="@Rohit Malhotra">
+
+## Pair programming for interactive design projects
+
+Used OpenHands as a pair programmer to do heavy lifting for a creative/interactive design project in p5js.
+
+I usually take around 2 days for high fidelity interactions (planning strategy + writing code + circling back with designer), did this in around 5hrs instead with the designer watching curiously the entire time.
+
+This showcases how OpenHands can accelerate creative and interactive design workflows, reducing development time by 75% while maintaining high quality output.
+
+[Original Tweet](https://x.com/rohit_malh5/status/1863995531657425225)
+
+</Update>

docs/usage/cloud/cloud-api.mdx

@@ -1,9 +1,11 @@
 ---
 title: Cloud API
-description: OpenHands Cloud provides a REST API that allows you to programmatically interact with the service. This guide explains how to obtain an API key and use the API to start conversations.
+description: OpenHands Cloud provides a REST API that allows you to programmatically interact with OpenHands.
+  This guide explains how to obtain an API key and use the API to start conversations and retrieve their status.
 ---
 
-For more detailed information about the API, refer to the [OpenHands API Reference](https://docs.all-hands.dev/swagger-ui/).
+For the available API endpoints, refer to the
+[OpenHands API Reference](https://docs.all-hands.dev/api-reference).
 
 ## Obtaining an API Key
 
@@ -16,7 +18,7 @@ To use the OpenHands Cloud API, you'll need to generate an 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](/static/img/docs/api-key-generation.png)
+![API Key Generation](/static/img/api-key-generation.png)
 
 ## API Usage
 
@@ -33,87 +35,81 @@ To start a new conversation with OpenHands to perform a task, you'll need to mak
 
 #### Examples
 
-<details>
-<summary>cURL</summary>
 
-```bash
-curl -X POST "https://app.all-hands.dev/api/conversations" \
-  -H "Authorization: Bearer YOUR_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
-    "repository": "yourusername/your-repo"
-  }'
-```
-</details>
+<Accordion title="cURL">
+  ```bash
+  curl -X POST "https://app.all-hands.dev/api/conversations" \
+    -H "Authorization: Bearer YOUR_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d '{
+      "initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
+      "repository": "yourusername/your-repo"
+    }'
+  ```
+</Accordion>
 
-<details>
-<summary>Python (with requests)</summary>
+<Accordion title="Python (with requests)">
+  ```python
+  import requests
 
-```python
-import requests
+  api_key = "YOUR_API_KEY"
+  url = "https://app.all-hands.dev/api/conversations"
 
-api_key = "YOUR_API_KEY"
-url = "https://app.all-hands.dev/api/conversations"
-
-headers = {
-    "Authorization": f"Bearer {api_key}",
-    "Content-Type": "application/json"
-}
-
-data = {
-    "initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
-    "repository": "yourusername/your-repo"
-}
-
-response = requests.post(url, headers=headers, json=data)
-conversation = response.json()
-
-print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation['conversation_id']}")
-print(f"Status: {conversation['status']}")
-```
-</details>
-
-<details>
-<summary>TypeScript/JavaScript (with fetch)</summary>
-
-```typescript
-const apiKey = "YOUR_API_KEY";
-const url = "https://app.all-hands.dev/api/conversations";
-
-const headers = {
-  "Authorization": `Bearer ${apiKey}`,
-  "Content-Type": "application/json"
-};
-
-const data = {
-  initial_user_msg: "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
-  repository: "yourusername/your-repo"
-};
-
-async function startConversation() {
-  try {
-    const response = await fetch(url, {
-      method: "POST",
-      headers: headers,
-      body: JSON.stringify(data)
-    });
-
-    const conversation = await response.json();
-
-    console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.id}`);
-    console.log(`Status: ${conversation.status}`);
-
-    return conversation;
-  } catch (error) {
-    console.error("Error starting conversation:", error);
+  headers = {
+      "Authorization": f"Bearer {api_key}",
+      "Content-Type": "application/json"
   }
-}
 
-startConversation();
-```
+  data = {
+      "initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
+      "repository": "yourusername/your-repo"
+  }
 
-</details>
+  response = requests.post(url, headers=headers, json=data)
+  conversation = response.json()
+
+  print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation['conversation_id']}")
+  print(f"Status: {conversation['status']}")
+  ```
+</Accordion>
+
+<Accordion title="TypeScript/JavaScript (with fetch)">
+  ```typescript
+  const apiKey = "YOUR_API_KEY";
+  const url = "https://app.all-hands.dev/api/conversations";
+
+  const headers = {
+    "Authorization": `Bearer ${apiKey}`,
+    "Content-Type": "application/json"
+  };
+
+  const data = {
+    initial_user_msg: "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
+    repository: "yourusername/your-repo"
+  };
+
+  async function startConversation() {
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: headers,
+        body: JSON.stringify(data)
+      });
+
+      const conversation = await response.json();
+
+      console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.id}`);
+      console.log(`Status: ${conversation.status}`);
+
+      return conversation;
+    } catch (error) {
+      console.error("Error starting conversation:", error);
+    }
+  }
+
+  startConversation();
+  ```
+</Accordion>
 
 #### Response
 
@@ -145,14 +141,12 @@ GET https://app.all-hands.dev/api/conversations/{conversation_id}
 
 #### Example
 
-<details>
-<summary>cURL</summary>
-
-```bash
-curl -X GET "https://app.all-hands.dev/api/conversations/{conversation_id}" \
-  -H "Authorization: Bearer YOUR_API_KEY"
-```
-</details>
+<Accordion title="cURL">
+  ```bash
+  curl -X GET "https://app.all-hands.dev/api/conversations/{conversation_id}" \
+    -H "Authorization: Bearer YOUR_API_KEY"
+  ```
+</Accordion>
 
 #### Response
 

docs/usage/cloud/cloud-issue-resolver.mdx

@@ -1,33 +0,0 @@
----
-title: Cloud Issue Resolver
-description: The Cloud Issue Resolver automates code fixes and provides intelligent assistance for your repositories on GitHub.
----
-
-## Setup
-
-The Cloud Issue Resolver is available automatically when you grant OpenHands Cloud repository access:
-- [GitHub repository access](./github-installation#adding-repository-access)
-
-## Usage
-
-After granting OpenHands Cloud repository access, you can use the Cloud Issue Resolver on issues and pull requests in your repositories.
-
-### Working with Issues
-
-On your repository, label an issue with `openhands` or add a message starting with
-`@openhands`. OpenHands will:
-1. Comment on the issue to let you know it is working on it
-   - You can click on the link to track the progress on OpenHands Cloud
-2. Open a pull request if it determines that the issue has been successfully resolved
-3. Comment on the issue with a summary of the performed tasks and a link to the PR
-
-### Working with Pull Requests
-
-To get OpenHands to work on pull requests, mention `@openhands` in comments to:
-- Ask questions
-- Request updates
-- Get code explanations
-
-OpenHands will:
-1. Comment to let you know it is working on it
-2. Perform the requested task

docs/usage/cloud/cloud-ui.mdx

@@ -1,28 +1,38 @@
 ---
 title: Cloud UI
-description: The Cloud UI provides a web interface for interacting with OpenHands AI. This page explains how to access and use the OpenHands Cloud UI.
+description: The Cloud UI provides a web interface for interacting with OpenHands. This page provides references on
+ how to use the OpenHands Cloud UI.
 ---
 
+## Landing Page
 
-## Accessing the UI
+The landing page is where you can:
 
-The OpenHands Cloud UI can be accessed at [app.all-hands.dev](https://app.all-hands.dev). You'll need to sign in with your GitHub or GitLab account to access the interface.
-
-
-## Key Features
-
-For detailed information about the features available in the OpenHands Cloud UI, please refer to the [Key Features](../key-features) section of the documentation.
+- [Add GitHub repository access](/usage/cloud/github-installation#adding-github-repository-access) to OpenHands.
+- [Select a GitHub repo](/usage/cloud/github-installation#working-with-github-repos-in-openhands-cloud) or
+  [a GitLab repo](/usage/cloud/gitlab-installation#working-with-gitlab-repos-in-openhands-cloud) to start working on.
+- See `Suggested Tasks` for repositories that OpenHands has access to.
+- Launch an empty conversation using `Launch from Scratch`.
 
 ## Settings
 
-The settings page allows you to:
+The Settings page allows you to:
 
-- Configure your account preferences.
-- Manage repository access.
-- Generate API keys for programmatic access.
-- Generate custom secrets for the agent.
+- [Configure GitHub repository access](/usage/cloud/github-installation#modifying-repository-access) for OpenHands.
+- [Install the OpenHands Slack app](/usage/cloud/slack-installation).
+- Set application settings like your preferred language, notifications and other preferences.
+- Add credits to your account.
+- [Generate custom secrets](/usage/common-settings#secrets-management).
+- [Create API keys to work with OpenHands programmatically](/usage/cloud/cloud-api).
+- Change your email address.
+
+## Key Features
+
+For an overview of the key features available inside a conversation, please refer to the [Key Features](/usage/key-features)
+section of the documentation.
 
 ## Next Steps
 
-- [Use the Cloud Issue Resolver](./cloud-issue-resolver) to automate code fixes and get assistance.
-- [Learn about the Cloud API](./cloud-api) for programmatic access.
+- [Install GitHub Integration](/usage/cloud/github-installation) to use OpenHands with your GitHub repositories.
+- [Install GitLab Integration](/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories.
+- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.

docs/usage/cloud/github-installation.mdx

@@ -1,7 +1,7 @@
 ---
 title: GitHub Integration
 description: This guide walks you through the process of installing OpenHands Cloud for your GitHub repositories. Once
-  set up, it will allow OpenHands to work with your GitHub repository through the Cloud UI or straight from GitHub issues!
+  set up, it will allow OpenHands to work with your GitHub repository through the Cloud UI or straight from GitHub!
 ---
 
 ## Prerequisites
@@ -35,13 +35,13 @@ You can grant OpenHands access to specific GitHub repositories:
 
 You can modify GitHub repository access at any time by:
 - Selecting `Add GitHub repos` on the landing page or
-- Visiting the Settings page and selecting `Configure GitHub Repositories` under the `Git` tab
+- Visiting the Settings page and selecting `Configure GitHub Repositories` under the `Integrations` tab
 
-## Working With Github Repos in Openhands Cloud
+## Working With GitHub Repos in Openhands Cloud
 
 Once you've granted GitHub repository access, you can start working with your GitHub repository. Use the `select a repo`
 and `select a branch` dropdowns to select the appropriate repository and branch you'd like OpenHands to work on. Then
-click on `Launch` to start the session!
+click on `Launch` to start the conversation!
 
 ![Connect Repo](/static/img/connect-repo.png)
 
@@ -67,5 +67,5 @@ To get OpenHands to work on pull requests, mention `@openhands` in the comments
 
 ## Next Steps
 
-- [Access the Cloud UI](./cloud-ui) to interact with the web interface
-- [Use the Cloud API](./cloud-api) to programmatically interact with OpenHands
+- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
+- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.

docs/usage/cloud/gitlab-installation.mdx

@@ -1,23 +1,31 @@
 ---
 title: GitLab Integration
-description: This guide walks you through the process of installing and configuring OpenHands Cloud for your GitLab repositories.
+description: This guide walks you through the process of installing OpenHands Cloud for your GitLab repositories. Once
+  set up, it will allow OpenHands to work with your GitLab repository.
 ---
 
 ## Prerequisites
 
-- A GitLab account
-- Access to OpenHands Cloud
+- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a GitLab account](/usage/cloud/openhands-cloud).
 
-## Installation Steps
+## Adding GitLab Repository Access
 
-1. Log in to [OpenHands Cloud](https://app.all-hands.dev)
-2. If you haven't connected your GitLab account yet:
-   - Click on `Log in with GitLab`
-   - Authorize the OpenHands application
+Upon signing into OpenHands Cloud with a GitLab account, OpenHands will have access to your repositories.
 
+## Working With GitLab Repos in Openhands Cloud
 
+After signing in with a Gitlab account, use the `select a repo` and `select a branch` dropdowns to select the
+appropriate repository and branch you'd like OpenHands to work on. Then click on `Launch` to start the conversation!
+
+![Connect Repo](/static/img/connect-repo.png)
+
+## Using Tokens with Reduced Scopes
+
+OpenHands requests an API-scoped token during OAuth authentication. By default, this token is provided to the agent.
+To restrict the agent's permissions, you can define a custom secret `GITLAB_TOKEN`, which will override the default token assigned to the agent.
+While the high-permission API token is still requested and used for other components of the application (e.g. opening merge requests), the agent will not have access to it.
 
 ## Next Steps
 
-- [Access the Cloud UI](./cloud-ui) to interact with the web interface
-- [Use the Cloud API](./cloud-api) to programmatically interact with OpenHands
+- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
+- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.

docs/usage/cloud/openhands-cloud.mdx

@@ -14,13 +14,13 @@ You'll be prompted to connect with your GitHub or GitLab account:
 2. Review the permissions requested by OpenHands and authorize the application.
    - OpenHands will require certain permissions from your account. To read more about these permissions,
      you can click the `Learn more` link on the authorization page.
+3. Review and accept the `terms of service` and select `Continue`.
 
 ## Next Steps
 
 Once you've connected your account, you can:
 
-- [Install GitHub Integration](./github-installation) to use OpenHands with your GitHub repositories
-- [Install GitLab Integration](./gitlab-installation) to use OpenHands with your GitLab repositories
-- [Access the Cloud UI](./cloud-ui) to interact with the web interface
-- [Use the Cloud API](./cloud-api) to programmatically interact with OpenHands
-- [Set up the Cloud Issue Resolver](./cloud-issue-resolver) to automate code fixes and provide intelligent assistance
+- [Install GitHub Integration](/usage/cloud/github-installation) to use OpenHands with your GitHub repositories.
+- [Install GitLab Integration](/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories.
+- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
+- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.

docs/usage/cloud/slack-installation.mdx

@@ -0,0 +1,82 @@
+---
+title: Slack Integration (Beta)
+description: This guide walks you through installing the OpenHands Slack app.
+---
+
+<iframe
+  className="w-full aspect-video"
+  src="https://www.youtube.com/embed/hbloGmfZsJ4"
+  title="OpenHands Slack Integration Tutorial"
+  frameBorder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+  allowFullScreen>
+</iframe>
+
+## Prerequisites
+
+- Access to OpenHands Cloud.
+
+## Installation Steps
+
+<AccordionGroup>
+<Accordion title="Install Slack App (only for Slack admins/owners)">
+
+  **This step is for Slack admins/owners**
+
+  1. Make sure you have permissions to install Apps to your workspace.
+  2. Click the button below to install OpenHands Slack App <a target="_blank" href="https://slack.com/oauth/v2/authorize?client_id=7477886716822.8729519890534&scope=app_mentions:read,chat:write,users:read,channels:history,groups:history,mpim:history,im:history&user_scope=channels:history,groups:history,im:history,mpim:history"><img alt="Add to Slack" height="40" width="139" src="https://platform.slack-edge.com/img/add_to_slack.png" srcSet="https://platform.slack-edge.com/img/add_to_slack.png 1x, https://platform.slack-edge.com/img/add_to_slack@2x.png 2x" /></a>
+  3. In the top right corner, select the workspace to install the OpenHands Slack app.
+  4. Review permissions and click allow.
+
+</Accordion>
+
+<Accordion title="Authorize Slack App (for all Slack workspace members)">
+
+  **Make sure your Slack workspace admin/owner has installed OpenHands Slack App first.**
+
+  Every user in the Slack workspace (including admins/owners) must link their OpenHands Cloud account to the OpenHands Slack App. To do this:
+  1. Visit [integrations settings](https://app.all-hands.dev/settings/integrations) in OpenHands Cloud.
+  2. Click `Install OpenHands Slack App`.
+  3. In the top right corner, select the workspace to install the OpenHands Slack app.
+  4. Review permissions and click allow.
+
+  Depending on the workspace settings, you may need approval from your Slack admin to authorize the Slack App.
+
+</Accordion>
+
+</AccordionGroup>
+
+
+## Working With the Slack App
+
+To start a new conversation, you can mention `@openhands` in a new message or a thread inside any Slack channel.
+
+Once a conversation is started, all thread messages underneath it will be follow-up messages to OpenHands.
+
+To send follow-up messages for the same conversation, mention `@openhands` in a thread reply to the original message. You must be the user who started the conversation.
+
+## Example conversation
+
+### Start a new conversation, and select repo
+
+Conversation is started by mentioning `@openhands`.
+
+![slack-create-convo.png](/static/img/slack-create-convo.png)
+
+### See agent response and send follow up messages
+
+Initial request is followed up by mentioning `@openhands` in a thread reply.
+
+![slack-results-and-follow-up.png](/static/img/slack-results-and-follow-up.png)
+
+## Pro tip
+
+You can mention a repo name when starting a new conversation in the following formats
+
+1. "My-Repo" repo (e.g `@openhands in the openhands repo ...`)
+2. "All-Hands-AI/OpenHands" (e.g `@openhands in All-Hands-AI/OpenHands ...`)
+
+The repo match is case insensitive. If a repo name match is made, it will kick off the conversation.
+If the repo name partially matches against multiple repos, you'll be asked to select a repo from the filtered list.
+
+![slack-pro-tip.png](/static/img/slack-pro-tip.png)

docs/usage/common-settings.mdx

@@ -0,0 +1,52 @@
+---
+title: OpenHands Settings
+description: Overview of some of the settings available in OpenHands.
+---
+
+## Openhands Cloud vs Running on Your Own
+
+There are some differences between the settings available in OpenHands Cloud and those available when running OpenHands
+on your own:
+* [OpenHands Cloud settings](/usage/cloud/cloud-ui#settings)
+* [Settings available when running on your own](/usage/how-to/gui-mode#settings)
+
+Refer to these pages for more detailed information.
+
+## Secrets Management
+
+OpenHands provides a secrets manager that allows you to securely store and manage sensitive information that can be
+accessed by the agent during runtime, such as API keys. These secrets are automatically exported as environment
+variables in the agent's runtime environment.
+
+### Accessing the Secrets Manager
+
+In the Settings page, navigate to the `Secrets` tab. Here, you'll see a list of all your existing custom secrets.
+
+### Adding a New Secret
+1. Click `Add a new secret`.
+2. Fill in the following fields:
+   - **Name**: A unique identifier for your secret (e.g., `AWS_ACCESS_KEY`). This will be the environment variable name.
+   - **Value**: The sensitive information you want to store.
+   - **Description** (optional): A brief description of what the secret is used for, which is also provided to the agent.
+3. Click `Add secret` to save.
+
+### Editing a Secret
+
+1. Click the `Edit` button next to the secret you want to modify.
+2. You can update the name and description of the secret.
+<Note>
+  For security reasons, you cannot view or edit the value of an existing secret. If you need to change the
+  value, delete the secret and create a new one.
+</Note>
+
+### Deleting a Secret
+
+1. Click the `Delete` button next to the secret you want to remove.
+2. Select `Confirm` to delete the secret.
+
+### Using Secrets in the Agent
+ - All custom secrets are automatically exported as environment variables in the agent's runtime environment.
+ - You can access them in your code using standard environment variable access methods
+   (e.g., `os.environ['SECRET_NAME']` in Python).
+ - Example: If you create a secret named `OPENAI_API_KEY`, you can access it in your code as
+   `process.env.OPENAI_API_KEY` in JavaScript or `os.environ['OPENAI_API_KEY']` in Python.

docs/usage/configuration-options.mdx

@@ -1,28 +1,17 @@
 ---
 title: Configuration Options
-description: This page outlines all available configuration options for OpenHands, allowing you to customize its behavior and integrate it with other services. In GUI Mode, any settings applied through the Settings UI will take precedence.
+description: This page outlines all available configuration options for OpenHands, allowing you to customize its
+  behavior and integrate it with other services.
 ---
 
+<Note>
+   In GUI Mode, any settings applied through the Settings UI will take precedence.
+</Note>
+
 ## Core Configuration
 
 The core configuration options are defined in the `[core]` section of the `config.toml` file.
 
-### API Keys
-- `e2b_api_key`
-  - Type: `str`
-  - Default: `""`
-  - Description: API key for E2B
-
-- `modal_api_token_id`
-  - Type: `str`
-  - Default: `""`
-  - Description: API token ID for Modal
-
-- `modal_api_token_secret`
-  - Type: `str`
-  - Default: `""`
-  - Description: API token secret for Modal
-
 ### Workspace
 - `workspace_base` **(Deprecated)**
   - Type: `str`

docs/usage/faqs.mdx

@@ -0,0 +1,96 @@
+---
+title: FAQs
+description: Frequently asked questions about OpenHands
+icon: question
+---
+
+## Getting Started
+
+### I'm new to OpenHands. Where should I start?
+
+1. **Quick start**: Use [OpenHands Cloud](/usage/cloud/openhands-cloud) to get started quickly with
+  [GitHub](/usage/cloud/github-installation), [GitLab](/usage/cloud/gitlab-installation),
+  and [Slack](/usage/cloud/slack-installation) integrations.
+2. **Run on your own**: If you prefer to run it on your own hardware, follow our [Getting Started guide](/usage/local-setup).
+3. **First steps**: Complete the [start building tutorial](/usage/getting-started) to learn the basics.
+
+### Can I use OpenHands for production workloads?
+
+OpenHands is meant to be run by a single user on their local workstation. It is not appropriate for multi-tenant
+deployments where multiple users share the same instance. There is no built-in authentication, isolation, or scalability.
+
+If you're interested in running OpenHands in a multi-tenant environment, check out the source-available,
+commercially-licensed [OpenHands Cloud Helm Chart](https://github.com/all-Hands-AI/OpenHands-cloud).
+
+<Info>
+Using OpenHands for work? We'd love to chat! Fill out
+[this short form](https://docs.google.com/forms/d/e/1FAIpQLSet3VbGaz8z32gW9Wm-Grl4jpt5WgMXPgJ4EDPVmCETCBpJtQ/viewform)
+to join our Design Partner program, where you'll get early access to commercial features and the opportunity to provide
+input on our product roadmap.
+</Info>
+
+## Safety and Security
+
+### It's doing stuff without asking, is that safe?
+
+**Generally yes, but with important considerations.** OpenHands runs all code in a secure, isolated Docker container
+(called a "sandbox") that is separate from your host system. However, the safety depends on your configuration:
+
+**What's protected:**
+- Your host system files and programs (unless you mount them using [this feature](/usage/runtimes/docker#connecting-to-your-filesystem))
+- Host system resources
+- Other containers and processes
+
+**Potential risks to consider:**
+- The agent can access the internet from within the container.
+- If you provide credentials (API keys, tokens), the agent can use them.
+- Mounted files and directories can be modified or deleted.
+- Network requests can be made to external services.
+
+For detailed security information, see our [Runtime Architecture](/usage/architecture/runtime),
+[Security Configuration](/usage/configuration-options#security-configuration),
+and [Hardened Docker Installation](/usage/runtimes/docker#hardened-docker-installation) documentation.
+
+## File Storage and Access
+
+### Where are my files stored?
+
+Your files are stored in different locations depending on how you've configured OpenHands:
+
+**Default behavior (no file mounting):**
+- Files created by the agent are stored inside the runtime Docker container.
+- These files are temporary and will be lost when the container is removed.
+- The agent works in the `/workspace` directory inside the runtime container.
+
+**When you mount your local filesystem (following [this](/usage/runtimes/docker#connecting-to-your-filesystem)):**
+- Your local files are mounted into the container's `/workspace` directory.
+- Changes made by the agent are reflected in your local filesystem.
+- Files persist after the container is stopped.
+
+<Warning>
+Be careful when mounting your filesystem - the agent can modify or delete any files in the mounted directory.
+</Warning>
+
+## Development Tools and Environment
+
+### How do I get the dev tools I need?
+
+OpenHands comes with a basic runtime environment that includes Python and Node.js.
+It also has the ability to install any tools it needs, so usually it's sufficient to ask it to set up its environment.
+
+If you would like to set things up more systematically, you can:
+- **Use setup.sh**: Add a [setup.sh file](/usage/prompting/repository#setup-script) file to
+  your repository, which will be run every time the agent starts.
+- **Use a custom sandbox**: Use a [custom docker image](/usage/how-to/custom-sandbox-guide) to initialize the sandbox.
+
+### Something's not working. Where can I get help?
+
+1. **Search existing issues**: Check our [GitHub issues](https://github.com/All-Hands-AI/OpenHands/issues) to see if
+  others have encountered the same problem.
+2. **Join our community**: Get help from other users and developers:
+   - [Slack community](https://join.slack.com/t/openhands-ai/shared_invite/zt-3847of6xi-xuYJIPa6YIPg4ElbDWbtSA)
+   - [Discord server](https://discord.gg/ESHStjSjD4)
+3. **Check our troubleshooting guide**: Common issues and solutions are documented in
+  [Troubleshooting](/usage/troubleshooting/troubleshooting).
+4. **Report bugs**: If you've found a bug, please [create an issue](https://github.com/All-Hands-AI/OpenHands/issues/new)
+  and fill in as much detail as possible.

docs/usage/getting-started.mdx

@@ -1,6 +1,6 @@
 ---
 title: Start Building
-description: So you've [run OpenHands](./installation) and have [set up your LLM](./installation#setup). Now what?
+description: So you've [run OpenHands](/usage/installation). Now what?
 icon: code
 ---
 

docs/usage/how-to/cli-mode.mdx

@@ -1,23 +1,56 @@
 ---
-title: CLI Mode
-description: CLI mode provides a powerful interactive Command-Line Interface (CLI) that lets you engage with OpenHands directly from your terminal.
+title: CLI
+description: The Command-Line Interface (CLI) provides a powerful interface 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.
+This mode is different from the [headless mode](/usage/how-to/headless-mode), which is non-interactive and better
+for scripting.
+
+<iframe
+  className="w-full aspect-video"
+  src="https://www.youtube.com/embed/PfvIx4y8h7w"
+  title="OpenHands CLI Tutorial"
+  frameBorder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
+  allowFullScreen>
+</iframe>
 
 ## Getting Started
 
 ### Running with Python
 
-1. Ensure you have followed the [Development setup instructions](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
-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:
+**Note** - OpenHands requires Python version 3.12 or higher (Python 3.14 is not currently supported)
 
+1. Install OpenHands using pip:
 ```bash
-poetry run python -m openhands.cli.main
+pip install openhands-ai
 ```
 
+  Or if you prefer not to manage your own Python environment, you can use `uvx`:
+
+```bash
+uvx --python 3.12 --from openhands-ai openhands
+```
+
+2. Launch an interactive OpenHands conversation from the command line:
+```bash
+openhands
+```
+
+<Note>
+  If you have cloned the repository, you can also run the CLI directly using Poetry:
+
+  poetry run python -m openhands.cli.main
+</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.
+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`.
 
 ### Running with Docker
 
@@ -31,23 +64,30 @@ This command opens an interactive prompt where you can type tasks or commands an
 ```bash
 docker run -it \
     --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-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-state:/.openhands-state \
+    -v ~/.openhands:/.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.41 \
+    docker.all-hands.dev/all-hands-ai/openhands:0.47 \
     python -m openhands.cli.main --override-cli-mode true
 ```
 
-This launches the CLI in Docker, allowing you to interact with OpenHands as described above.
+<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)` ensures files created by the agent in your workspace have the correct permissions.
 
+The conversation history will be saved in `~/.openhands/sessions`.
+
 ## Interactive CLI Overview
 
 ### What is CLI Mode?

docs/usage/how-to/custom-sandbox-guide.mdx

@@ -1,6 +1,7 @@
 ---
 title: Custom Sandbox
-description: This guide is for users that would like to use their own custom Docker image for the runtime. For example, with certain tools or programming languages pre-installed.
+description: This guide is for users that would like to use their own custom Docker image for the runtime.
+  For example, with certain tools or programming languages pre-installed.
 ---
 
 The sandbox is where the agent performs its tasks. Instead of running commands directly on your computer
@@ -46,7 +47,7 @@ This will produce a new image called `custom-image`, which will be available in
 
 ## Using the Docker Command
 
-When running OpenHands using [the docker command](/usage/installation#start-the-app), replace
+When running OpenHands using [the docker command](/usage/local-setup#start-the-app), replace
 `-e SANDBOX_RUNTIME_CONTAINER_IMAGE=...` with `-e SANDBOX_BASE_CONTAINER_IMAGE=<custom image name>`:
 
 ```commandline

docs/usage/how-to/github-action.mdx

@@ -48,6 +48,6 @@ The customization options you can set are:
 | `LLM_MODEL`                      | Variable | Set the LLM to use with OpenHands                                                                   | `LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"` |
 | `OPENHANDS_MAX_ITER`             | Variable | Set max limit for agent iterations                                                                  | `OPENHANDS_MAX_ITER=10`                            |
 | `OPENHANDS_MACRO`                | Variable | Customize default macro for invoking the resolver                                                   | `OPENHANDS_MACRO=@resolveit`                       |
-| `OPENHANDS_BASE_CONTAINER_IMAGE` | Variable | Custom Sandbox ([learn more](https://docs.all-hands.dev/modules/usage/how-to/custom-sandbox-guide)) | `OPENHANDS_BASE_CONTAINER_IMAGE="custom_image"`    |
+| `OPENHANDS_BASE_CONTAINER_IMAGE` | Variable | Custom Sandbox ([learn more](/usage/how-to/custom-sandbox-guide))                                   | `OPENHANDS_BASE_CONTAINER_IMAGE="custom_image"`    |
 | `TARGET_BRANCH`                  | Variable | Merge to branch other than `main`                                                                   | `TARGET_BRANCH="dev"`                              |
 | `TARGET_RUNNER`                  | Variable | Target runner to execute the agent workflow (default ubuntu-latest)                                 | `TARGET_RUNNER="custom-runner"`                    |

docs/usage/how-to/gui-mode.mdx

@@ -1,14 +1,13 @@
 ---
-title: GUI Mode
-description: OpenHands provides a Graphical User Interface (GUI) mode for interacting with the AI assistant.
+title: GUI
+description: High level overview of the Graphical User Interface (GUI) in OpenHands.
 ---
 
-## Installation and Setup
+## Prerequisites
 
-1. Follow the installation instructions to install OpenHands.
-2. After running the command, access OpenHands at [http://localhost:3000](http://localhost:3000).
+- [OpenHands is running](/usage/local-setup)
 
-## Interacting with the GUI
+## Overview
 
 ### Initial Setup
 
@@ -19,16 +18,23 @@ description: OpenHands provides a Graphical User Interface (GUI) mode for intera
 3. Enter the corresponding `API Key` for your chosen provider.
 4. Click `Save Changes` to apply the settings.
 
-### Version Control Tokens
+### Settings
 
-OpenHands supports multiple version control providers. You can configure tokens for multiple providers simultaneously.
+You can use the Settings page at any time to:
 
-#### GitHub Token Setup
+- Setup the LLM provider and model for OpenHands.
+- [Setup the search engine](/usage/search-engine-setup).
+- [Configure MCP servers](/usage/mcp).
+- [Connect to GitHub](/usage/how-to/gui-mode#github-setup) and [connect to GitLab](/usage/how-to/gui-mode#gitlab-setup).
+- Set application settings like your preferred language, notifications and other preferences.
+- [Manage custom secrets](/usage/common-settings#secrets-management).
+
+#### GitHub Setup
 
 OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if provided:
 
-<details>
-  <summary>Setting Up a GitHub Token</summary>
+<AccordionGroup>
+<Accordion title="Setting Up a GitHub Token">
 
   1. **Generate a Personal Access Token (PAT)**:
    - On GitHub, go to Settings > Developer Settings > Personal Access Tokens > Tokens (classic).
@@ -37,16 +43,11 @@ OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if pro
      - `repo` (Full control of private repositories)
    - **Fine-Grained Tokens**
      - All Repositories (You can select specific repositories, but this will impact what returns in repo search)
-     - Minimal Permissions ( Select `Meta Data = Read-only` read for search, `Pull Requests = Read and Write` and `Content = Read and Write` for branch creation)
+     - 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.
+   - In the Settings page, navigate to the `Integrations` tab.
    - Paste your token in the `GitHub Token` field.
    - Click `Save Changes` to apply the changes.
-</details>
-
-<details>
-  <summary>Organizational Token Policies</summary>
 
   If you're working with organizational repositories, additional setup may be required:
 
@@ -59,15 +60,12 @@ OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if pro
    - Look for the organization under `Organization access`.
    - If required, click `Enable SSO` next to your organization.
    - Complete the SSO authorization process.
-</details>
-
-<details>
-  <summary>Troubleshooting</summary>
+</Accordion>
 
+<Accordion title="Troubleshooting">
   Common issues and solutions:
 
   - **Token Not Recognized**:
-     - Ensure the token is properly saved in settings.
      - Check that the token hasn't expired.
      - Verify the token has the required scopes.
      - Try regenerating the token.
@@ -81,15 +79,15 @@ OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if pro
      - The app will show a green checkmark if the token is valid.
      - Try accessing a repository to confirm permissions.
      - Check the browser console for any error messages.
-</details>
+</Accordion>
+</AccordionGroup>
 
-#### GitLab Token Setup
+#### GitLab Setup
 
 OpenHands automatically exports a `GITLAB_TOKEN` to the shell environment if provided:
 
-<details>
-  <summary>Setting Up a GitLab Token</summary>
-
+<AccordionGroup>
+<Accordion title="Setting Up a GitLab Token">
   1. **Generate a Personal Access Token (PAT)**:
    - On GitLab, go to User Settings > Access Tokens.
    - Create a new token with the following scopes:
@@ -99,15 +97,17 @@ OpenHands automatically exports a `GITLAB_TOKEN` to the shell environment if pro
      - `write_repository` (Write repository)
    - 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.
+   - In the Settings page, navigate to the `Integrations` tab.
    - Paste your token in the `GitLab Token` field.
    - Click `Save Changes` to apply the changes.
-</details>
 
-<details>
-  <summary>Troubleshooting</summary>
+  3. **(Optional): Restrict agent permissions**
+   - Create another PAT using Step 1 and exclude `api` scope .
+   - In the Settings page, in the `Secrets` tab, create a new secret `GITLAB_TOKEN` and paste your lower scope token.
+   - OpenHands will use the higher scope token, and the agent will use the lower scope token
+</Accordion>
 
+<Accordion title="Troubleshooting">
   Common issues and solutions:
 
   - **Token Not Recognized**:
@@ -119,25 +119,79 @@ OpenHands automatically exports a `GITLAB_TOKEN` to the shell environment if pro
      - Verify project access permissions.
      - Check if the token has the necessary scopes.
      - For group/organization repositories, ensure you have proper access.
-</details>
+</Accordion>
+</AccordionGroup>
 
-### Advanced Settings
+#### BitBucket Setup (Coming soon ...)
+<AccordionGroup>
+<Accordion title="Setting Up a BitBucket Password">
+1. **Generate an App Password**:
+   - On BitBucket, go to Personal Settings > App Password.
+   - Create a new password with the following scopes:
+     - `repository: read`
+     - `repository: write`
+     - `pull requests: read`
+     - `pull requests: write`
+     - `issues: read`
+     - `issues: write`
+   - App passwords are non-expiring token. OpenHands will migrate to using API tokens in the future.
+  2. **Enter Token in OpenHands**:
+   - In the Settings page, navigate to the `Integrations` tab.
+   - Paste your token in the `BitBucket Token` field.
+   - Click `Save Changes` to apply the changes.
+</Accordion>
 
-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.
+<Accordion title="Troubleshooting">
+  Common issues and solutions:
 
-### Interacting with the AI
+  - **Token Not Recognized**:
+     - Ensure the token is properly saved in settings.
+     - Check that the token hasn't expired.
+     - Verify the token has the required scopes.
 
-1. Type your prompt in the input box.
-2. Click the send button or press Enter to submit your message.
-3. The AI will process your input and provide a response in the chat window.
-4. You can continue the conversation by asking follow-up questions or providing additional information.
+  - **Verifying Token Works**:
+     - The app will show a green checkmark if the token is valid.
+     - Try accessing a repository to confirm permissions.
+     - Check the browser console for any error messages.
+</Accordion>
+
+</AccordionGroup>
+
+#### Advanced Settings
+
+The `Advanced` settings allows configuration of additional LLM settings. Inside the Settings page, under the `LLM` tab,
+toggle `Advanced` options to access additional settings.
+
+- Custom Model: Use the `Custom Model` text box to manually enter a model. Make sure to use the correct prefix based on litellm docs.
+- Base URL: Specify a `Base URL` if required by your LLM provider.
+- Memory Condensation: The memory condenser manages the LLM's context by ensuring only the most important and relevant information is presented.
+- Confirmation Mode: Enabling this mode will cause OpenHands to confirm an action with the user before performing it.
+
+### Key Features
+
+For an overview of the key features available inside a conversation, please refer to the [Key Features](/usage/key-features)
+section of the documentation.
+
+### Status Indicator
+
+The status indicator located in the bottom left of the screen will cycle through a number of states as a new conversation
+is loaded. Typically these include:
+
+* `Disconnected` : The frontend is not connected to any conversation.
+* `Connecting` : The frontend is connecting a websocket to a conversation.
+* `Building Runtime...` : The server is building a runtime. This is typically in development mode only while building a docker image.
+* `Starting Runtime...` : The server is starting a new runtime instance - probably a new docker container or remote runtime.
+* `Initializing Agent...` : The server is starting the agent loop (This step does not appear at present with Nested runtimes).
+* `Setting up workspace...` : Usually this means a `git clone ...` operation.
+* `Setting up git hooks` : Setting up the git pre commit hooks for the workspace.
+* `Agent is awaiting user input...` : Ready to go!
 
 ## Tips for Effective Use
 
 - Be specific in your requests to get the most accurate and helpful responses, as described in the [prompting best practices](../prompting/prompting-best-practices).
-- Use one of the recommended models, as described in the [LLMs section](usage/llms/llms.md).
+- Use one of the recommended models, as described in the [LLMs section](/usage/llms/llms).
 
-Remember, the GUI mode of OpenHands is designed to make your interaction with the AI assistant as smooth and intuitive
-as possible. Don't hesitate to explore its features to maximize your productivity.
+## Other Ways to Run Openhands
+- [Run OpenHands in a scriptable headless mode.](/usage/how-to/headless-mode)
+- [Run OpenHands with a friendly CLI.](/usage/how-to/cli-mode)
+- [Run OpenHands on GitHub issues with a GitHub action.](/usage/how-to/github-action)

docs/usage/how-to/headless-mode.mdx

@@ -1,9 +1,10 @@
 ---
-title: Headless Mode
-description: You can run OpenHands with a single command, without starting the web application. This makes it easy to write scripts and automate tasks with OpenHands.
+title: Headless
+description: You can run OpenHands with a single command, without starting the web application. This makes it easy to
+  write scripts and automate tasks with OpenHands.
 ---
 
-This is different from [CLI Mode](./cli-mode), which is interactive, and better for active development.
+This is different from [the CLI](./cli-mode), which is interactive, and better for active development.
 
 ## With Python
 
@@ -17,41 +18,78 @@ poetry run python -m openhands.core.main -t "write a bash script that prints hi"
 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
+### Working with Repositories
 
-To run OpenHands in Headless mode with Docker:
+You can specify a repository for OpenHands to work with using `--selected-repo` or the `SANDBOX_SELECTED_REPO` environment variable:
 
-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-sonnet-4-20250514"`)
-   - `LLM_API_KEY` - your API key (e.g. `export LLM_API_KEY="sk_test_12345"`)
-
-2. Run the following Docker command:
+> **Note**: Currently, authentication tokens (GITHUB_TOKEN, GITLAB_TOKEN, or BITBUCKET_TOKEN) are required for all repository operations, including public repositories. This is a known limitation that may be addressed in future versions to allow tokenless access to public repositories.
 
 ```bash
+# Using command-line argument
+poetry run python -m openhands.core.main \
+  --selected-repo "owner/repo-name" \
+  -t "analyze the codebase and suggest improvements"
+
+# Using environment variable
+export SANDBOX_SELECTED_REPO="owner/repo-name"
+poetry run python -m openhands.core.main -t "fix any linting issues"
+
+# Authentication tokens are currently required for ALL repository operations (public and private)
+# This includes GitHub, GitLab, and Bitbucket repositories
+export GITHUB_TOKEN="your-token"  # or GITLAB_TOKEN, BITBUCKET_TOKEN
+poetry run python -m openhands.core.main \
+  --selected-repo "owner/repo-name" \
+  -t "review the security implementation"
+
+# Using task files instead of inline task
+echo "Review the README and suggest improvements" > task.txt
+poetry run python -m openhands.core.main -f task.txt --selected-repo "owner/repo"
+```
+
+## With Docker
+
+Set environment variables and run the Docker command:
+
+```bash
+# Set required environment variables
+export SANDBOX_VOLUMES="/path/to/workspace"  # See SANDBOX_VOLUMES docs for details
+export LLM_MODEL="anthropic/claude-sonnet-4-20250514"
+export LLM_API_KEY="your-api-key"
+export SANDBOX_SELECTED_REPO="owner/repo-name"  # Optional: requires GITHUB_TOKEN
+export GITHUB_TOKEN="your-token"  # Required for repository operations
+
+# Run OpenHands
 docker run -it \
     --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
     -e SANDBOX_USER_ID=$(id -u) \
     -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
     -e LLM_API_KEY=$LLM_API_KEY \
     -e LLM_MODEL=$LLM_MODEL \
+    -e SANDBOX_SELECTED_REPO=$SANDBOX_SELECTED_REPO \
+    -e GITHUB_TOKEN=$GITHUB_TOKEN \
     -e LOG_ALL_EVENTS=true \
     -v /var/run/docker.sock:/var/run/docker.sock \
-    -v ~/.openhands-state:/.openhands-state \
+    -v ~/.openhands:/.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.41 \
+    docker.all-hands.dev/all-hands-ai/openhands:0.47 \
     python -m openhands.core.main -t "write a bash script that prints hi"
 ```
 
+> **Note**: If you used OpenHands before version 0.44, run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history.
+
 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.
 
-## Advanced Headless Configurations
+## Additional Options
 
-To view all available configuration options for headless mode, run the Python command with the `--help` flag.
+Common command-line options:
+- `-d "/path/to/workspace"` - Set working directory
+- `-f task.txt` - Load task from file
+- `-i 50` - Set max iterations
+- `-b 10.0` - Set budget limit (USD)
+- `--no-auto-continue` - Interactive mode
 
-### Additional Logs
+Run `poetry run python -m openhands.core.main --help` for all options, or use a [`config.toml` file](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml) for more flexibility.
 
-For the headless mode to log all the agent actions, in the terminal run: `export LOG_ALL_EVENTS=true`
+Set `export LOG_ALL_EVENTS=true` to log all agent actions.

docs/usage/installation.mdx

@@ -1,19 +1,19 @@
 ---
 title: Quick Start
-description: Running OpenHands Cloud or running on your local system.
+description: Running OpenHands Cloud or running on your own.
 icon: rocket
 ---
 
 ## OpenHands Cloud
 
-The easiest way to get started with OpenHands is on OpenHands Cloud, which comes with $50 in free credits for new users.
+The easiest way to get started with OpenHands is on OpenHands Cloud, which comes with $20 in free credits for new users.
 
 To get started with OpenHands Cloud, visit [app.all-hands.dev](https://app.all-hands.dev).
 
 For more information see [getting started with OpenHands Cloud.](/usage/cloud/openhands-cloud)
 
-## Running OpenHands Locally
+## Running OpenHands on Your Own
 
 Run OpenHands on your local system and bring your own LLM and API key.
 
-For more information see [running OpenHands locally.](/usage/local-setup)
+For more information see [running OpenHands on your own.](/usage/local-setup)

docs/usage/llms/google-llms.mdx

@@ -8,7 +8,7 @@ description: OpenHands uses LiteLLM to make calls to Google's chat models. You c
 When running OpenHands, you'll need to set the following in the OpenHands UI through the Settings under the `LLM` tab:
 - `LLM Provider` to `Gemini`
 - `LLM Model` to the model you will be using.
-If the model is not in the list, enable `Advanced` options, and enter it in `Custom Model` 
+If the model is not in the list, enable `Advanced` options, and enter it in `Custom Model`
 (e.g. gemini/<model-name> like `gemini/gemini-2.0-flash`).
 - `API Key` to your Gemini API key
 
@@ -26,5 +26,5 @@ VERTEXAI_LOCATION="<your-gcp-location>"
 Then set the following in the OpenHands UI through the Settings under the `LLM` tab:
 - `LLM Provider` to `VertexAI`
 - `LLM Model` to the model you will be using.
-If the model is not in the list, enable `Advanced` options, and enter it in `Custom Model` 
+If the model is not in the list, enable `Advanced` options, and enter it in `Custom Model`
 (e.g. vertex_ai/&lt;model-name&gt;).

docs/usage/llms/groq.mdx

@@ -8,7 +8,7 @@ description: OpenHands uses LiteLLM to make calls to chat models on Groq. You ca
 When running OpenHands, you'll need to set the following in the OpenHands UI through the Settings under the `LLM` tab:
 - `LLM Provider` to `Groq`
 - `LLM Model` to the model you will be using. [Visit here to see the list of
-models that Groq hosts](https://console.groq.com/docs/models). If the model is not in the list, 
+models that Groq hosts](https://console.groq.com/docs/models). If the model is not in the list,
 enable `Advanced` options, and enter it in `Custom Model` (e.g. groq/<model-name> like `groq/llama3-70b-8192`).
 - `API key` to your Groq API key. To find or create your Groq API Key, [see here](https://console.groq.com/keys).
 

docs/usage/llms/litellm-proxy.mdx

@@ -16,7 +16,7 @@ To use LiteLLM proxy with OpenHands, you need to:
 
 ## Supported Models
 
-The supported models depend on your LiteLLM proxy configuration. OpenHands supports any model that your LiteLLM proxy 
+The supported models depend on your LiteLLM proxy configuration. OpenHands supports any model that your LiteLLM proxy
 is configured to handle.
 
 Refer to your LiteLLM proxy configuration for the list of available models and their names.

docs/usage/llms/llms.mdx

@@ -14,23 +14,28 @@ recommendations for model selection. Our latest benchmarking results can be foun
 
 Based on these findings and community feedback, these are the latest models that have been verified to work reasonably well with OpenHands:
 
+### Cloud / API-Based Models
+
 - [anthropic/claude-sonnet-4-20250514](https://www.anthropic.com/api) (recommended)
 - [openai/o4-mini](https://openai.com/index/introducing-o3-and-o4-mini/)
 - [gemini/gemini-2.5-pro](https://blog.google/technology/google-deepmind/gemini-model-thinking-updates-march-2025/)
 - [deepseek/deepseek-chat](https://api-docs.deepseek.com/)
-- [all-hands/openhands-lm-32b-v0.1](https://www.all-hands.dev/blog/introducing-openhands-lm-32b----a-strong-open-coding-agent-model) -- available through [OpenRouter](https://openrouter.ai/all-hands/openhands-lm-32b-v0.1)
 
+If you have successfully run OpenHands with specific providers, we encourage you to open a PR to share your setup process
+to help others using the same provider!
+
+For a full list of the providers and models available, please consult the
+[litellm documentation](https://docs.litellm.ai/docs/providers).
 
 <Warning>
 OpenHands will issue many prompts to the LLM you configure. Most of these LLMs cost money, so be sure to set spending
 limits and monitor usage.
 </Warning>
 
-If you have successfully run OpenHands with specific providers, we encourage you to open a PR to share your setup process 
-to help others using the same provider!
+### Local / Self-Hosted Models
 
-For a full list of the providers and models available, please consult the
-[litellm documentation](https://docs.litellm.ai/docs/providers).
+- [mistralai/devstral-small](https://www.all-hands.dev/blog/devstral-a-new-state-of-the-art-open-model-for-coding-agents) (20 May 2025) -- also available through [OpenRouter](https://openrouter.ai/mistralai/devstral-small:free)
+- [all-hands/openhands-lm-32b-v0.1](https://www.all-hands.dev/blog/introducing-openhands-lm-32b----a-strong-open-coding-agent-model) (31 March 2025) -- also available through [OpenRouter](https://openrouter.ai/all-hands/openhands-lm-32b-v0.1)
 
 <Note>
 Most current local and open source models are not as powerful. When using such models, you may see long
@@ -68,6 +73,15 @@ We have a few guides for running OpenHands with specific model providers:
 - [OpenAI](/usage/llms/openai-llms)
 - [OpenRouter](/usage/llms/openrouter)
 
+## Model Customization
+
+LLM providers have specific settings that can be customized to optimize their performance with OpenHands, such as:
+
+- **Custom Tokenizers**: For specialized models, you can add a suitable tokenizer
+- **Native Tool Calling**: Toggle native function/tool calling capabilities
+
+For detailed information about model customization, see [LLM Configuration Options](configuration-options#llm-customization).
+
 ### API retries and rate limits
 
 LLM providers typically have rate limits, sometimes very low, and may require retries. OpenHands will automatically

docs/usage/llms/local-llms.mdx

@@ -6,73 +6,85 @@ description: When using a Local LLM, OpenHands may have limited functionality. I
 ## News
 
 - 2025/05/21: We collaborated with Mistral AI and released [Devstral Small](https://mistral.ai/news/devstral) that achieves [46.8% on SWE-Bench Verified](https://github.com/SWE-bench/experiments/pull/228)!
-- 2025/03/31: We released an open model OpenHands LM v0.1 32B that achieves 37.1% on SWE-Bench Verified
+- 2025/03/31: We released an open model OpenHands LM 32B v0.1 that achieves 37.1% on SWE-Bench Verified
 ([blog](https://www.all-hands.dev/blog/introducing-openhands-lm-32b----a-strong-open-coding-agent-model), [model](https://huggingface.co/all-hands/openhands-lm-32b-v0.1)).
 
+## Quickstart: Running OpenHands with a Local LLM using LM Studio
 
-## Quickstart: Running OpenHands on Your Macbook
+This guide explains how to serve a local Devstral LLM using [LM Studio](https://lmstudio.ai/) and have OpenHands connect to it.
 
-### Serve the model on your Macbook
+We recommend:
+- **LM Studio** as the local model server, which handles metadata downloads automatically and offers a simple, user-friendly interface for configuration.
+- **Devstral Small 2505** as the LLM for software development, trained on real GitHub issues and optimized for agent-style workflows like OpenHands.
 
-We recommend using [LMStudio](https://lmstudio.ai/) for serving these models locally.
+### Hardware Requirements
 
-1. Download [LM Studio](https://lmstudio.ai/) and install it
+Running Devstral requires a recent GPU with at least 16GB of VRAM, or a Mac with Apple Silicon (M1, M2, etc.) with at least 32GB of RAM.
 
-2. Download the model:
-   - Option 1: Directly download the LLM from [this link](https://lmstudio.ai/model/devstral-small-2505-mlx) or by searching for the name `Devstral-Small-2505` in LM Studio
-   - Option 2: Download a LLM in GGUF format. For example, to download [Devstral Small 2505 GGUF](https://huggingface.co/mistralai/Devstral-Small-2505_gguf), using `huggingface-cli download mistralai/Devstral-Small-2505_gguf --local-dir mistralai/Devstral-Small-2505_gguf`. Then in bash terminal, run `lms import {model_name}` in the directory where you've downloaded the model checkpoint (e.g. run `lms import devstralQ4_K_M.gguf` in `mistralai/Devstral-Small-2505_gguf`)
+### 1. Install LM Studio
 
-3. Open LM Studio application, you should first switch to `power user` mode, and then open the developer tab:
+Download and install the LM Studio desktop app from [lmstudio.ai](https://lmstudio.ai/).
 
-![image](./screenshots/1_select_power_user.png)
+### 2. Download Devstral Small
 
-4. Then click `Select a model to load` on top of the application:
+1. Make sure to set the User Interface Complexity Level to "Power User", by clicking on the appropriate label at the bottom of the window.
+2. Click the "Discover" button (Magnifying Glass icon) on the left navigation bar to open the Models download page.
 
-![image](./screenshots/2_select_model.png)
+![image](./screenshots/01_lm_studio_open_model_hub.png)
 
-5. And choose the model you want to use, holding `option` on mac to enable advanced loading options:
+3. Search for the "Devstral Small 2505" model, confirm it's the official Mistral AI (mistralai) model, then proceed to download.
 
-![image](./screenshots/3_select_devstral.png)
+![image](./screenshots/02_lm_studio_download_devstral.png)
 
-6. You should then pick an appropriate context window for OpenHands based on your hardware configuration (larger than 32768 is recommended for using OpenHands, but too large may cause you to run out of memory); Flash attention is also recommended if it works on your machine.
+4. Wait for the download to finish.
 
-![image](./screenshots/4_set_context_window.png)
+### 3. Load the Model
 
-7. And you should start the server (if it is not already in `Running` status), un-toggle `Serve on Local Network` and remember the port number of the LMStudio URL (`1234` is the port number for `http://127.0.0.1:1234` in this example):
+1. Click the "Developer" button (Console icon) on the left navigation bar to open the Developer Console.
+2. Click the "Select a model to load" dropdown at the top of the application window.
 
-![image](./screenshots/5_copy_url.png)
+![image](./screenshots/03_lm_studio_open_load_model.png)
 
-8. Finally, you can click the `copy` button near model name to copy the model name (`imported-models/uncategorized/devstralq4_k_m.gguf` in this example):
+3. Enable the "Manually choose model load parameters" switch.
+4. Select 'Devstral Small 2505' from the model list.
 
-![image](./screenshots/6_copy_to_get_model_name.png)
+![image](./screenshots/04_lm_studio_setup_devstral_part_1.png)
 
-### Start OpenHands with locally served model
+5. Enable the "Show advanced settings" switch at the bottom of the Model settings flyout to show all the available settings.
+6. Set "Context Length" to at least 32768 and enable Flash Attention.
+7. Click "Load Model" to start loading the model.
 
-Check [the installation guide](https://docs.all-hands.dev/modules/usage/installation) to make sure you have all the prerequisites for running OpenHands.
+![image](./screenshots/05_lm_studio_setup_devstral_part_2.png)
+
+### 4. Start the LLM server
+
+1. Enable the switch next to "Status" at the top-left of the Window.
+2. Take note of the Model API Identifier shown on the sidebar on the right.
+
+![image](./screenshots/06_lm_studio_start_server.png)
+
+### 5. Start OpenHands
+
+1. Check [the installation guide](/usage/local-setup) and ensure all prerequisites are met before running OpenHands, then run:
 
 ```bash
-export LMSTUDIO_MODEL_NAME="imported-models/uncategorized/devstralq4_k_m.gguf" # <- Replace this with the model name you copied from LMStudio
-export LMSTUDIO_URL="http://host.docker.internal:1234"  # <- Replace this with the port from LMStudio
-
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik
-
-mkdir -p ~/.openhands-state && echo '{"language":"en","agent":"CodeActAgent","max_iterations":null,"security_analyzer":null,"confirmation_mode":false,"llm_model":"lm_studio/'$LMSTUDIO_MODEL_NAME'","llm_api_key":"dummy","llm_base_url":"'$LMSTUDIO_URL/v1'","remote_runtime_resource_factor":null,"github_token":null,"enable_default_condenser":true,"user_consents_to_analytics":true}' > ~/.openhands-state/settings.json
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
     -e LOG_ALL_EVENTS=true \
     -v /var/run/docker.sock:/var/run/docker.sock \
-    -v ~/.openhands-state:/.openhands-state \
+    -v ~/.openhands:/.openhands \
     -p 3000:3000 \
     --add-host host.docker.internal:host-gateway \
     --name openhands-app \
-    docker.all-hands.dev/all-hands-ai/openhands:0.41
+    docker.all-hands.dev/all-hands-ai/openhands:0.47
 ```
 
-Once your server is running -- you can visit `http://localhost:3000` in your browser to use OpenHands with local Devstral model:
+2. Wait until the server is running (see log below):
 ```
 Digest: sha256:e72f9baecb458aedb9afc2cd5bc935118d1868719e55d50da73190d3a85c674f
-Status: Image is up to date for docker.all-hands.dev/all-hands-ai/openhands:0.41
+Status: Image is up to date for docker.all-hands.dev/all-hands-ai/openhands:0.47
 Starting OpenHands...
 Running OpenHands as root
 14:22:13 - openhands:INFO: server_config.py:50 - Using config class None
@@ -82,53 +94,88 @@ INFO:     Application startup complete.
 INFO:     Uvicorn running on http://0.0.0.0:3000 (Press CTRL+C to quit)
 ```
 
+3. Visit `http://localhost:3000` in your browser.
 
-## Advanced: Serving LLM on GPUs
+### 6. Configure OpenHands to use the LLM server
 
-### Download model checkpoints
+Once you open OpenHands in your browser, you'll need to configure it to use the local LLM server you just started.
 
-<Note>
-The model checkpoints downloaded here should NOT be in GGUF format.
-</Note>
+When started for the first time, OpenHands will prompt you to set up the LLM provider.
 
-For example, to download [OpenHands LM 32B v0.1](https://huggingface.co/all-hands/openhands-lm-32b-v0.1):
+1. Click "see advanced settings" to open the LLM Settings page.
+
+![image](./screenshots/07_openhands_open_advanced_settings.png)
+
+2. Enable the "Advanced" switch at the top of the page to show all the available settings.
+
+3. Set the following values:
+    - **Custom Model**: `openai/mistralai/devstral-small-2505` (the Model API identifier from LM Studio, prefixed with "openai/")
+    - **Base URL**: `http://host.docker.internal:1234/v1`
+    - **API Key**: `local-llm`
+
+4. Click "Save Settings" to save the configuration.
+
+![image](./screenshots/08_openhands_configure_local_llm_parameters.png)
+
+That's it! You can now start using OpenHands with the local LLM server.
+
+If you encounter any issues, let us know on [Slack](https://join.slack.com/t/openhands-ai/shared_invite/zt-3847of6xi-xuYJIPa6YIPg4ElbDWbtSA) or [Discord](https://discord.gg/ESHStjSjD4).
+
+## Advanced: Alternative LLM Backends
+
+This section describes how to run local LLMs with OpenHands using alternative backends like Ollama, SGLang, or vLLM — without relying on LM Studio.
+
+### Create an OpenAI-Compatible Endpoint with Ollama
+
+- Install Ollama following [the official documentation](https://ollama.com/download).
+- Example launch command for Devstral Small 2505:
 
 ```bash
-huggingface-cli download all-hands/openhands-lm-32b-v0.1 --local-dir all-hands/openhands-lm-32b-v0.1
+# ⚠️ WARNING: OpenHands requires a large context size to work properly.
+# When using Ollama, set OLLAMA_CONTEXT_LENGTH to at least 32768.
+# The default (4096) is way too small — not even the system prompt will fit, and the agent will not behave correctly.
+OLLAMA_CONTEXT_LENGTH=32768 OLLAMA_HOST=0.0.0.0:11434 OLLAMA_KEEP_ALIVE=-1 nohup ollama serve &
+ollama pull devstral:latest
 ```
 
-### Create an OpenAI-Compatible Endpoint With SGLang
+### Create an OpenAI-Compatible Endpoint with vLLM or SGLang
+
+First, download the model checkpoints. For [Devstral Small 2505](https://huggingface.co/mistralai/Devstral-Small-2505):
+
+```bash
+huggingface-cli download mistralai/Devstral-Small-2505 --local-dir mistralai/Devstral-Small-2505
+```
+
+#### Serving the model using SGLang
 
 - Install SGLang following [the official documentation](https://docs.sglang.ai/start/install.html).
-- Example launch command for OpenHands LM 32B (with at least 2 GPUs):
+- Example launch command for Devstral Small 2505 (with at least 2 GPUs):
 
 ```bash
 SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1 python3 -m sglang.launch_server \
-    --model all-hands/openhands-lm-32b-v0.1 \
-    --served-model-name openhands-lm-32b-v0.1 \
+    --model mistralai/Devstral-Small-2505 \
+    --served-model-name Devstral-Small-2505 \
     --port 8000 \
     --tp 2 --dp 1 \
     --host 0.0.0.0 \
     --api-key mykey --context-length 131072
 ```
 
-### Create an OpenAI-Compatible Endpoint with vLLM
+#### Serving the model using vLLM
 
 - Install vLLM following [the official documentation](https://docs.vllm.ai/en/latest/getting_started/installation.html).
-- Example launch command for OpenHands LM 32B (with at least 2 GPUs):
+- Example launch command for Devstral Small 2505 (with at least 2 GPUs):
 
 ```bash
-vllm serve all-hands/openhands-lm-32b-v0.1 \
+vllm serve mistralai/Devstral-Small-2505 \
     --host 0.0.0.0 --port 8000 \
     --api-key mykey \
     --tensor-parallel-size 2 \
-    --served-model-name openhands-lm-32b-v0.1
+    --served-model-name Devstral-Small-2505 \
     --enable-prefix-caching
 ```
 
-## Advanced: Run and Configure OpenHands
-
-### Run OpenHands
+### Run OpenHands (Alternative Backends)
 
 #### Using Docker
 
@@ -137,24 +184,20 @@ Run OpenHands using [the official docker run command](../installation#start-the-
 #### Using Development Mode
 
 Use the instructions in [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md) to build OpenHands.
-Ensure `config.toml` exists by running `make setup-config` which will create one for you. In the `config.toml`, enter the following:
-
-```
-[core]
-workspace_base="/path/to/your/workspace"
-
-[llm]
-model="openhands-lm-32b-v0.1"
-ollama_base_url="http://localhost:8000"
-```
 
 Start OpenHands using `make run`.
 
-### Configure OpenHands
+### Configure OpenHands (Alternative Backends)
 
-Once OpenHands is running, you'll need to set the following in the OpenHands UI through the Settings under the `LLM` tab:
-1. Enable `Advanced` options.
-2. Set the following:
-- `Custom Model` to `openai/<served-model-name>` (e.g. `openai/openhands-lm-32b-v0.1`)
-- `Base URL` to `http://host.docker.internal:8000`
-- `API key` to the same string you set when serving the model (e.g. `mykey`)
+Once OpenHands is running, open the Settings page in the UI and go to the `LLM` tab.
+
+1. Click **"see advanced settings"** to access the full configuration panel.
+2. Enable the **Advanced** toggle at the top of the page.
+3. Set the following parameters, if you followed the examples above:
+   - **Custom Model**: `openai/<served-model-name>`
+     e.g. `openai/devstral` if you're using Ollama, or `openai/Devstral-Small-2505` for SGLang or vLLM.
+   - **Base URL**: `http://host.docker.internal:<port>/v1`
+     Use port `11434` for Ollama, or `8000` for SGLang and vLLM.
+   - **API Key**:
+     - For **Ollama**: any placeholder value (e.g. `dummy`, `local-llm`)
+     - For **SGLang** or **vLLM**: use the same key provided when starting the server (e.g. `mykey`)

docs/usage/llms/openrouter.mdx

@@ -9,6 +9,6 @@ When running OpenHands, you'll need to set the following in the OpenHands UI thr
 * `LLM Provider` to `OpenRouter`
 * `LLM Model` to the model you will be using.
 [Visit here to see a full list of OpenRouter models](https://openrouter.ai/models).
-If the model is not in the list, enable `Advanced` options, and enter it in 
+If the model is not in the list, enable `Advanced` options, and enter it in
 `Custom Model` (e.g. openrouter/<model-name> like `openrouter/anthropic/claude-3.5-sonnet`).
 * `API Key` to your OpenRouter API key.

docs/usage/local-setup.mdx

@@ -1,6 +1,6 @@
 ---
 title: Getting Started
-description: Getting started with running OpenHands locally.
+description: Getting started with running OpenHands on your own.
 ---
 
 ## Recommended Methods for Running Openhands on Your Local System
@@ -10,6 +10,7 @@ description: Getting started with running OpenHands locally.
 - MacOS with [Docker Desktop support](https://docs.docker.com/desktop/setup/install/mac-install/#system-requirements)
 - Linux
 - Windows with [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) and [Docker Desktop support](https://docs.docker.com/desktop/setup/install/windows-install/#system-requirements)
+- Windows without WSL (see [Windows Without WSL Guide](/usage/windows-without-wsl))
 
 A system with a modern processor and a minimum of **4GB RAM** is recommended to run OpenHands.
 
@@ -55,6 +56,10 @@ A system with a modern processor and a minimum of **4GB RAM** is recommended to
   The docker command below to start the app must be run inside the WSL terminal.
   </Note>
 
+  **Alternative: Windows without WSL**
+
+  If you prefer to run OpenHands on Windows without WSL or Docker, see our [Windows Without WSL Guide](/usage/windows-without-wsl).
+
 </Accordion>
 
 </AccordionGroup>
@@ -62,19 +67,21 @@ A system with a modern processor and a minimum of **4GB RAM** is recommended to
 ### Start the App
 
 ```bash
-docker pull docker.all-hands.dev/all-hands-ai/runtime:0.40-nikolaik
+docker pull docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik
 
 docker run -it --rm --pull=always \
-    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.40-nikolaik \
+    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.47-nikolaik \
     -e LOG_ALL_EVENTS=true \
     -v /var/run/docker.sock:/var/run/docker.sock \
-    -v ~/.openhands-state:/.openhands-state \
+    -v ~/.openhands:/.openhands \
     -p 3000:3000 \
     --add-host host.docker.internal:host-gateway \
     --name openhands-app \
-    docker.all-hands.dev/all-hands-ai/openhands:0.40
+    docker.all-hands.dev/all-hands-ai/openhands:0.47
 ```
 
+> **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.
+
 You'll find OpenHands running at http://localhost:3000!
 
 ### Setup
@@ -109,10 +116,32 @@ OpenHands requires an API key to access most language models. Here's how to get
 
 </Accordion>
 
+<Accordion title="Google (Gemini)">
+
+1. Create a Google account if you don't already have one.
+2. [Generate an API key](https://aistudio.google.com/apikey).
+3. [Set up billing](https://aistudio.google.com/usage?tab=billing).
+
+</Accordion>
+
+<Accordion title="Local LLM (e.g. LM Studio, llama.cpp, Ollama)">
+
+If your local LLM server isn’t behind an authentication proxy, you can enter any value as the API key (e.g. `local-key`, `test123`) — it won’t be used.
+
+</Accordion>
+
 </AccordionGroup>
 
 Consider setting usage limits to control costs.
 
+#### Using a Local LLM
+
+<Note>
+Effective use of local models for agent tasks requires capable hardware, along with models specifically tuned for instruction-following and agent-style behavior.
+</Note>
+
+To run OpenHands with a locally hosted language model instead of a cloud provider, see the [Local LLMs guide](/usage/llms/local-llms) for setup instructions.
+
 #### Setting Up Search Engine
 
 OpenHands can be configured to use a search engine to allow the agent to search the web for information when needed.
@@ -124,9 +153,6 @@ To enable search functionality in OpenHands:
 
 For more details, see the [Search Engine Setup](/usage/search-engine-setup) guide.
 
-
-Now you're ready to [get started with OpenHands](/usage/getting-started).
-
 ### Versions
 
 The [docker command above](/usage/local-setup#start-the-app) pulls the most recent stable release of OpenHands. You have other options as well:

docs/usage/mcp.mdx

@@ -1,6 +1,7 @@
 ---
 title: Model Context Protocol (MCP)
-description: This page outlines how to configure and use the Model Context Protocol (MCP) in OpenHands, allowing you to extend the agent's capabilities with custom tools.
+description: This page outlines how to configure and use the Model Context Protocol (MCP) in OpenHands, allowing you
+  to extend the agent's capabilities with custom tools.
 ---
 
 ## Overview

docs/usage/prompting/microagents-org.mdx

@@ -5,12 +5,14 @@ description: Organizations and users can define microagents that apply to all re
 
 ## Usage
 
-These microagents can be [any type of microagent](./microagents-overview#microagent-types) and will be loaded 
+These microagents can be [any type of microagent](./microagents-overview#microagent-types) and will be loaded
 accordingly. However, they are applied to all repositories belonging to the organization or user.
 
 Add a `.openhands` repository under the organization or user and create a `microagents` directory and place the
 microagents in that directory.
 
+For GitLab organizations, use `openhands-config` as the repository name instead of `.openhands`, since GitLab doesn't support repository names starting with non-alphanumeric characters.
+
 ## Example
 
 General microagent file example for organization `Great-Co` located inside the `.openhands` repository:
@@ -20,3 +22,5 @@ General microagent file example for organization `Great-Co` located inside the `
 * Document interfaces and public APIs; use implementation comments only for non-obvious logic.
 * Follow the same naming convention for variables, classes, constants, etc. already used in each repository.
 ```
+
+For GitLab organizations, the same microagent would be located inside the `openhands-config` repository.

docs/usage/prompting/microagents-overview.mdx

@@ -11,7 +11,7 @@ Currently OpenHands supports the following types of microagents:
 - [Keyword-Triggered Microagents](./microagents-keyword): Guidelines activated by specific keywords in prompts.
 
 To customize OpenHands' behavior, create a .openhands/microagents/ directory in the root of your repository and
-add `<microagent_name>.md` files inside.
+add `<microagent_name>.md` files inside. For repository-specific guidelines, you can ask OpenHands to analyze your repository and create a comprehensive `repo.md` file (see [General Microagents](./microagents-repo) for details).
 
 <Note>
 Loaded microagents take up space in the context window.

docs/usage/prompting/microagents-repo.mdx

@@ -17,13 +17,45 @@ Frontmatter should be enclosed in triple dashes (---) and may include the follow
 |-----------|-----------------------------------------|----------|----------------|
 | `agent`   | The agent this microagent applies to    | No       | 'CodeActAgent' |
 
-## Example
+## Creating a Comprehensive Repository Agent
+
+To create an effective repository agent, you can ask OpenHands to analyze your repository with a prompt like:
 
-General microagent file example located at `.openhands/microagents/repo.md`:
 ```
+Please browse the repository, look at the documentation and relevant code, and understand the purpose of this repository.
+
+Specifically, I want you to create a `.openhands/microagents/repo.md` file. This file should contain succinct information that summarizes:
+1. The purpose of this repository
+2. The general setup of this repo
+3. A brief description of the structure of this repo
+
+Read all the GitHub workflows under .github/ of the repository (if this folder exists) to understand the CI checks (e.g., linter, pre-commit), and include those in the repo.md file.
+```
+
+This approach helps OpenHands capture repository context efficiently, reducing the need for repeated searches during conversations and ensuring more accurate solutions.
+
+## Example Content
+
+A comprehensive repository agent file (`.openhands/microagents/repo.md`) should include:
+
+```
+# Repository Purpose
 This project is a TODO application that allows users to track TODO items.
 
+# Setup Instructions
 To set it up, you can run `npm run build`.
+
+# Repository Structure
+- `/src`: Core application code
+- `/tests`: Test suite
+- `/docs`: Documentation
+- `/.github`: CI/CD workflows
+
+# CI/CD Workflows
+- `lint.yml`: Runs ESLint on all JavaScript files
+- `test.yml`: Runs the test suite on pull requests
+
+# Development Guidelines
 Always make sure the tests are passing before committing changes. You can run the tests by running `npm run test`.
 ```
 

docs/usage/runtimes/daytona.mdx

@@ -3,7 +3,6 @@ title: Daytona Runtime
 description: You can use [Daytona](https://www.daytona.io/) as a runtime provider.
 ---
 
-
 ## Step 1: Retrieve Your Daytona API Key
 1. Visit the [Daytona Dashboard](https://app.daytona.io/dashboard/keys).
 2. Click **"Create Key"**.

docs/usage/runtimes/docker.mdx

@@ -3,8 +3,6 @@ title: Docker Runtime
 description: This is the default Runtime that's used when you start OpenHands.
 ---
 
-This is the default Runtime that's used when you start OpenHands.
-
 ## Image
 The `SANDBOX_RUNTIME_CONTAINER_IMAGE` from nikolaik is a pre-built runtime image
 that contains our Runtime server, as well as some basic utilities for Python and NodeJS.
@@ -128,3 +126,7 @@ docker network create openhands-network
 docker run # ... \
     --network openhands-network \
 ```
+
+<Note>
+**Docker Desktop Required**: Network isolation features, including custom networks and `host.docker.internal` routing, require Docker Desktop. Docker Engine alone does not support these features on localhost across custom networks. If you're using Docker Engine without Docker Desktop, network isolation may not work as expected.
+</Note>

docs/usage/runtimes/e2b.mdx

@@ -3,7 +3,8 @@ title: E2B Runtime
 description: E2B is an open-source secure cloud environment (sandbox) made for running AI-generated code and agents.
 ---
 
-[E2B](https://e2b.dev) offers [Python](https://pypi.org/project/e2b/) and [JS/TS](https://www.npmjs.com/package/e2b) SDK to spawn and control these sandboxes.
+[E2B](https://e2b.dev) offers [Python](https://pypi.org/project/e2b/) and [JS/TS](https://www.npmjs.com/package/e2b)
+SDK to spawn and control these sandboxes.
 
 ## Getting started
 
@@ -18,9 +19,13 @@ description: E2B is an open-source secure cloud environment (sandbox) made for r
     Full CLI API is [here](https://e2b.dev/docs/cli/installation).
 
 ## OpenHands sandbox
-You can use the E2B CLI to create a custom sandbox with a Dockerfile. Read the full guide [here](https://e2b.dev/docs/guide/custom-sandbox). The premade OpenHands sandbox for E2B is set up in the `containers` directory. and it's called `openhands`.
+
+You can use the E2B CLI to create a custom sandbox with a Dockerfile. Read the full guide
+[here](https://e2b.dev/docs/guide/custom-sandbox). The premade OpenHands sandbox for E2B is set up in the `containers`
+directory. and it's called `openhands`.
 
 ## Debugging
+
 You can connect to a running E2B sandbox with E2B CLI in your terminal.
 
 - List all running sandboxes (based on your API key)
@@ -34,5 +39,6 @@ You can connect to a running E2B sandbox with E2B CLI in your terminal.
     ```
 
 ## Links
+
 - [E2B Docs](https://e2b.dev/docs)
 - [E2B GitHub](https://github.com/e2b-dev/e2b)

docs/usage/runtimes/local.mdx

@@ -1,6 +1,8 @@
 ---
 title: Local Runtime
-description: The Local Runtime allows the OpenHands agent to execute actions directly on your local machine without using Docker. This runtime is primarily intended for controlled environments like CI pipelines or testing scenarios where Docker is not available.
+description: The Local Runtime allows the OpenHands agent to execute actions directly on your local machine without
+  using Docker. This runtime is primarily intended for controlled environments like CI pipelines or testing scenarios
+  where Docker is not available.
 ---
 
 <Warning>
@@ -15,7 +17,7 @@ Before using the Local Runtime, ensure that:
 1. You can run OpenHands using the [Development workflow](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md).
 2. For Linux and Mac, tmux is available on your system.
 3. For Windows, PowerShell is available on your system.
-    - Only [CLI mode](../how-to/cli-mode) and [headless mode](../how-to/headless-mode) are supported in Windows with Local Runtime. 
+    - Only [CLI mode](../how-to/cli-mode) and [headless mode](../how-to/headless-mode) are supported in Windows with Local Runtime.
 
 ## Configuration
 

docs/usage/runtimes/overview.mdx

@@ -9,8 +9,6 @@ commands.
 By default, OpenHands uses a [Docker-based runtime](/usage/runtimes/docker), running on your local computer.
 This means you only have to pay for the LLM you're using, and your code is only ever sent to the LLM.
 
-We also support other runtimes, which are typically managed by third-parties.
-
 Additionally, we provide a [Local Runtime](/usage/runtimes/local) that runs directly on your machine without Docker,
 which can be useful in controlled environments like CI pipelines.
 
@@ -21,6 +19,18 @@ OpenHands supports several different runtime environments:
 - [Docker Runtime](/usage/runtimes/docker) - The default runtime that uses Docker containers for isolation (recommended for most users).
 - [OpenHands Remote Runtime](/usage/runtimes/remote) - Cloud-based runtime for parallel execution (beta).
 - [Local Runtime](/usage/runtimes/local) - Direct execution on your local machine without Docker.
-- And more third-party runtimes:
-  - [Modal Runtime](/usage/runtimes/modal) - Runtime provided by our partners at Modal.
-  - [Daytona Runtime](/usage/runtimes/daytona) - Runtime provided by Daytona.
+
+### Third-Party Runtimes
+
+The following third-party runtimes are available when you install the `third_party_runtimes` extra:
+
+```bash
+pip install openhands-ai[third_party_runtimes]
+```
+
+- [E2B Runtime](/usage/runtimes/e2b) - Open source runtime using E2B sandboxes.
+- [Modal Runtime](/usage/runtimes/modal) - Serverless runtime using Modal infrastructure.
+- [Runloop Runtime](/usage/runtimes/runloop) - Cloud runtime using Runloop infrastructure.
+- [Daytona Runtime](/usage/runtimes/daytona) - Development environment runtime using Daytona.
+
+**Note**: These third-party runtimes are supported by their respective developers, not by the OpenHands team. For issues specific to these runtimes, please refer to their documentation or contact their support teams.

docs/usage/runtimes/remote.mdx

@@ -1,7 +1,11 @@
 ---
 title: Remote Runtime
-description: This runtime is specifically designed for agent evaluation purposes only through the [OpenHands evaluation harness](https://github.com/All-Hands-AI/OpenHands/tree/main/evaluation). It should not be used to launch production OpenHands applications.
+description: This runtime is specifically designed for agent evaluation purposes only through the
+  [OpenHands evaluation harness](https://github.com/All-Hands-AI/OpenHands/tree/main/evaluation). It should not be
+  used to launch production OpenHands applications.
 ---
 
-OpenHands Remote Runtime is currently in beta (read [here](https://runtime.all-hands.dev/) for more details), it allows you to launch runtimes
-in parallel in the cloud. Fill out [this form](https://docs.google.com/forms/d/e/1FAIpQLSckVz_JFwg2_mOxNZjCtr7aoBFI2Mwdan3f75J_TrdMS1JV2g/viewform) to apply if you want to try this out!
+OpenHands Remote Runtime is currently in beta (read [here](https://runtime.all-hands.dev/) for more details),
+it allows you to launch runtimes in parallel in the cloud. Fill out
+[this form](https://docs.google.com/forms/d/e/1FAIpQLSckVz_JFwg2_mOxNZjCtr7aoBFI2Mwdan3f75J_TrdMS1JV2g/viewform) to
+apply if you want to try this out!

docs/usage/runtimes/runloop.mdx

@@ -1,6 +1,7 @@
 ---
 title: Runloop Runtime
-description: Runloop provides a fast, secure and scalable AI sandbox (Devbox). Check out the [runloop docs](https://docs.runloop.ai/overview/what-is-runloop) for more detail.
+description: Runloop provides a fast, secure and scalable AI sandbox (Devbox). Check out the
+  [runloop docs](https://docs.runloop.ai/overview/what-is-runloop) for more detail.
 ---
 
 ## Access

docs/usage/search-engine-setup.mdx

@@ -1,6 +1,6 @@
 ---
 title: Search Engine Setup
-description: Configure OpenHands to use Tavily as a search engine
+description: Configure OpenHands to use Tavily as a search engine.
 ---
 
 ## Setting Up Search Engine in OpenHands
@@ -11,10 +11,10 @@ OpenHands can be configured to use [Tavily](https://tavily.com/) as a search eng
 
 To use the search functionality in OpenHands, you'll need to obtain a Tavily API key:
 
-1. Visit [Tavily's website](https://tavily.com/) and sign up for an account
-2. Navigate to the API section in your dashboard
-3. Generate a new API key
-4. Copy the API key (it should start with `tvly-`)
+1. Visit [Tavily's website](https://tavily.com/) and sign up for an account.
+2. Navigate to the API section in your dashboard.
+3. Generate a new API key.
+4. Copy the API key (it should start with `tvly-`).
 
 ### Configuring Search in OpenHands
 
@@ -22,13 +22,12 @@ Once you have your Tavily API key, you can configure OpenHands to use it:
 
 #### In the OpenHands UI
 
-1. Open OpenHands and navigate to the Settings page by clicking the gear icon
-2. In the LLM settings tab, locate the "Search API Key (Tavily)" field
-3. Enter your Tavily API key (starting with `tvly-`)
-4. Click "Save" to apply the changes
+1. Open OpenHands and navigate to the Settings page.
+2. Under the `LLM` tab, enter your Tavily API key (starting with `tvly-`) in the `Search API Key (Tavily)` field.
+3. Click `Save` to apply the changes.
 
 <Note>
-The search API key field is optional. If you don't provide a key, the search functionality will not be available to the agent.
+  The search API key field is optional. If you don't provide a key, the search functionality will not be available to the agent.
 </Note>
 
 #### Using Configuration Files
@@ -45,22 +44,23 @@ search_api_key = "tvly-your-api-key-here"
 
 When the search engine is configured:
 
-1. The agent can decide to search the web when it needs external information
-2. Search queries are sent to Tavily's API via [Tavily's MCP server](https://github.com/tavily-ai/tavily-mcp) which includes a variety of [tools](https://docs.tavily.com/documentation/api-reference/introduction) (search, extract, crawl, map).
-3. Results are returned and incorporated into the agent's context
-4. The agent can use this information to provide more accurate and up-to-date responses
+- The agent can decide to search the web when it needs external information.
+- Search queries are sent to Tavily's API via [Tavily's MCP server](https://github.com/tavily-ai/tavily-mcp) which
+  includes a variety of [tools](https://docs.tavily.com/documentation/api-reference/introduction) (search, extract, crawl, map).
+- Results are returned and incorporated into the agent's context.
+- The agent can use this information to provide more accurate and up-to-date responses.
 
 ### Limitations
 
-- Search results depend on Tavily's coverage and freshness
-- Usage may be subject to Tavily's rate limits and pricing tiers
-- The agent will only search when it determines that external information is needed
+- Search results depend on Tavily's coverage and freshness.
+- Usage may be subject to Tavily's rate limits and pricing tiers.
+- The agent will only search when it determines that external information is needed.
 
 ### Troubleshooting
 
 If you encounter issues with the search functionality:
 
-- Verify that your API key is correct and active
-- Check that your API key starts with `tvly-`
-- Ensure you have an active internet connection
-- Check Tavily's status page for any service disruptions
+- Verify that your API key is correct and active.
+- Check that your API key starts with `tvly-`.
+- Ensure you have an active internet connection.
+- Check Tavily's status page for any service disruptions.

docs/usage/troubleshooting/troubleshooting.mdx

@@ -31,9 +31,9 @@ On initial prompt, an error is seen with `Permission Denied` or `PermissionError
 
 **Resolution**
 
-* Check if the `~/.openhands-state` is owned by `root`. If so, you can:
-  * Change the directory's ownership: `sudo chown <user>:<user> ~/.openhands-state`.
-  * or update permissions on the directory: `sudo chmod 777 ~/.openhands-state`
+* Check if the `~/.openhands` is owned by `root`. If so, you can:
+  * Change the directory's ownership: `sudo chown <user>:<user> ~/.openhands`.
+  * or update permissions on the directory: `sudo chmod 777 ~/.openhands`
   * or delete it if you don’t need previous data. OpenHands will recreate it. You'll need to re-enter LLM settings.
 * If mounting a local directory, ensure your `WORKSPACE_BASE` has the necessary permissions for the user running
   OpenHands.
@@ -56,13 +56,16 @@ To fix this:
        -e SANDBOX_VSCODE_PORT=41234 \
        -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:latest \
        -v /var/run/docker.sock:/var/run/docker.sock \
-       -v ~/.openhands-state:/.openhands-state \
+       -v ~/.openhands:/.openhands \
        -p 3000:3000 \
        -p 41234:41234 \
        --add-host host.docker.internal:host-gateway \
        --name openhands-app \
        docker.all-hands.dev/all-hands-ai/openhands:latest
    ```
+
+   > **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.
+
 2. Make sure to expose the same port with `-p 41234:41234` in your Docker command.
 3. If running with the development workflow, you can set this in your `config.toml` file:
    ```toml

docs/usage/windows-without-wsl.mdx

@@ -0,0 +1,253 @@
+---
+title: Windows Without WSL
+description: Running OpenHands GUI on Windows without using WSL or Docker
+---
+
+# Running OpenHands GUI on Windows Without WSL
+
+This guide provides step-by-step instructions for running OpenHands on a Windows machine without using WSL or Docker.
+
+## Prerequisites
+
+1. **Windows 10/11** - A modern Windows operating system
+2. **PowerShell 7+** - While Windows PowerShell comes pre-installed on Windows 10/11, PowerShell 7+ is strongly recommended to avoid compatibility issues (see Troubleshooting section for "System.Management.Automation" errors)
+3. **.NET Core Runtime** - Required for the PowerShell integration via pythonnet
+4. **Python 3.12 or 3.13** - Python 3.12 or 3.13 is required (Python 3.14 is not supported due to pythonnet compatibility)
+5. **Git** - For cloning the repository and version control
+6. **Node.js and npm** - For running the frontend
+
+## Step 1: Install Required Software
+
+1. **Install Python 3.12 or 3.13**
+   - Download Python 3.12.x or 3.13.x from [python.org](https://www.python.org/downloads/)
+   - During installation, check "Add Python to PATH"
+   - Verify installation by opening PowerShell and running:
+     ```powershell
+     python --version
+     ```
+
+2. **Install PowerShell 7**
+   - Download and install PowerShell 7 from the [official PowerShell GitHub repository](https://github.com/PowerShell/PowerShell/releases)
+   - Choose the MSI installer appropriate for your system (x64 for most modern computers)
+   - Run the installer with default options
+   - Verify installation by opening a new terminal and running:
+     ```powershell
+     pwsh --version
+     ```
+   - Using PowerShell 7 (pwsh) instead of Windows PowerShell will help avoid "System.Management.Automation" errors
+
+3. **Install .NET Core Runtime**
+   - Download and install the .NET Core Runtime from [Microsoft's .NET download page](https://dotnet.microsoft.com/download)
+   - Choose the latest .NET Core Runtime (not SDK)
+   - Verify installation by opening PowerShell and running:
+     ```powershell
+     dotnet --info
+     ```
+   - This step is required for the PowerShell integration via pythonnet. Without it, OpenHands will fall back to a more limited PowerShell implementation.
+
+4. **Install Git**
+   - Download Git from [git-scm.com](https://git-scm.com/download/win)
+   - Use default installation options
+   - Verify installation:
+     ```powershell
+     git --version
+     ```
+
+5. **Install Node.js and npm**
+   - Download Node.js from [nodejs.org](https://nodejs.org/) (LTS version recommended)
+   - During installation, accept the default options which will install npm as well
+   - Verify installation:
+     ```powershell
+     node --version
+     npm --version
+     ```
+
+6. **Install Poetry**
+   - Open PowerShell as Administrator and run:
+     ```powershell
+     (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
+     ```
+   - Add Poetry to your PATH:
+     ```powershell
+     $env:Path += ";$env:APPDATA\Python\Scripts"
+     ```
+   - Verify installation:
+     ```powershell
+     poetry --version
+     ```
+
+## Step 2: Clone and Set Up OpenHands
+
+1. **Clone the Repository**
+   ```powershell
+   git clone https://github.com/All-Hands-AI/OpenHands.git
+   cd OpenHands
+   ```
+
+2. **Install Dependencies**
+   ```powershell
+   poetry install
+   ```
+
+   This will install all required dependencies, including:
+   - pythonnet - Required for Windows PowerShell integration
+   - All other OpenHands dependencies
+
+## Step 3: Run OpenHands
+
+1. **Build the Frontend**
+   ```powershell
+   cd frontend
+   npm install
+   npm run build
+   cd ..
+   ```
+
+   This will build the frontend files that the backend will serve.
+
+2. **Start the Backend**
+   ```powershell
+   # Make sure to use PowerShell 7 (pwsh) instead of Windows PowerShell
+   pwsh
+   $env:RUNTIME="local"; poetry run uvicorn openhands.server.listen:app --host 0.0.0.0 --port 3000 --reload --reload-exclude "./workspace"
+   ```
+
+   This will start the OpenHands app using the local runtime with PowerShell integration, available at `localhost:3000`.
+
+   > **Note**: If you encounter a `RuntimeError: Directory './frontend/build' does not exist` error, make sure you've built the frontend first using the command above.
+
+   > **Important**: Using PowerShell 7 (pwsh) instead of Windows PowerShell is recommended to avoid "System.Management.Automation" errors. If you encounter this error, see the Troubleshooting section below.
+
+3. **Alternatively, Run the Frontend in Development Mode (in a separate PowerShell window)**
+   ```powershell
+   cd frontend
+   npm run dev
+   ```
+
+4. **Access the OpenHands GUI**
+
+   Open your browser and navigate to:
+   ```
+   http://localhost:3000
+   ```
+
+   > **Note**: If you're running the frontend in development mode (using `npm run dev`), use port 3001 instead: `http://localhost:3001`
+
+## Installing and Running the CLI
+
+To install and run the OpenHands CLI on Windows without WSL, follow these steps:
+
+### 1. Install uv (Python Package Manager)
+
+Open PowerShell as Administrator and run:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### 2. Install .NET SDK (Required)
+
+The OpenHands CLI **requires** the .NET Core runtime for PowerShell integration. Without it, the CLI will fail to start with a `coreclr` error. Install the .NET SDK which includes the runtime:
+
+```powershell
+winget install Microsoft.DotNet.SDK.8
+```
+
+Alternatively, you can download and install the .NET SDK from the [official Microsoft website](https://dotnet.microsoft.com/download).
+
+After installation, restart your PowerShell session to ensure the environment variables are updated.
+
+### 3. Install and Run OpenHands
+
+After installing the prerequisites, you can install and run OpenHands with:
+
+```powershell
+uvx --python 3.12 --from openhands-ai openhands
+```
+
+### Troubleshooting CLI Issues
+
+#### CoreCLR Error
+
+If you encounter an error like `Failed to load CoreCLR` or `pythonnet.load('coreclr')` when running OpenHands CLI, this indicates that the .NET Core runtime is missing or not properly configured. To fix this:
+
+1. Install the .NET SDK as described in step 2 above
+2. Verify that your system PATH includes the .NET SDK directories
+3. Restart your PowerShell session completely after installing the .NET SDK
+4. Make sure you're using PowerShell 7 (pwsh) rather than Windows PowerShell
+
+To verify your .NET installation, run:
+
+```powershell
+dotnet --info
+```
+
+This should display information about your installed .NET SDKs and runtimes. If this command fails, the .NET SDK is not properly installed or not in your PATH.
+
+If the issue persists after installing the .NET SDK, try installing the specific .NET Runtime version 6.0 or later from the [.NET download page](https://dotnet.microsoft.com/download).
+
+## Limitations on Windows
+
+When running OpenHands on Windows without WSL or Docker, be aware of the following limitations:
+
+1. **Browser Tool Not Supported**: The browser tool is not currently supported on Windows.
+
+2. **.NET Core Requirement**: The PowerShell integration requires .NET Core Runtime to be installed. The CLI implementation attempts to load the CoreCLR at startup with `pythonnet.load('coreclr')` and will fail with an error if .NET Core is not properly installed.
+
+3. **Interactive Shell Commands**: Some interactive shell commands may not work as expected. The PowerShell session implementation has limitations compared to the bash session used on Linux/macOS.
+
+4. **Path Handling**: Windows uses backslashes (`\`) in paths, which may require adjustments when working with code examples designed for Unix-like systems.
+
+## Troubleshooting
+
+### "System.Management.Automation" Not Found Error
+
+If you encounter an error message stating that "System.Management.Automation" was not found, this typically indicates that you have a minimal version of PowerShell installed or that the .NET components required for PowerShell integration are missing.
+
+> **IMPORTANT**: This error is most commonly caused by using the built-in Windows PowerShell (powershell.exe) instead of PowerShell 7 (pwsh.exe). Even if you installed PowerShell 7 during the prerequisites, you may still be using the older Windows PowerShell by default.
+
+To resolve this issue:
+
+1. **Install the latest version of PowerShell 7** from the official Microsoft repository:
+   - Visit [https://github.com/PowerShell/PowerShell/releases](https://github.com/PowerShell/PowerShell/releases)
+   - Download and install the latest MSI package for your system architecture (x64 for most systems)
+   - During installation, ensure you select the following options:
+     - "Add PowerShell to PATH environment variable"
+     - "Register Windows PowerShell 7 as the default shell"
+     - "Enable PowerShell remoting"
+   - The installer will place PowerShell 7 in `C:\Program Files\PowerShell\7` by default
+
+2. **Restart your terminal or command prompt** to ensure the new PowerShell is available
+
+3. **Verify the installation** by running:
+   ```powershell
+   pwsh --version
+   ```
+
+   You should see output indicating PowerShell 7.x.x
+
+4. **Run OpenHands using PowerShell 7** instead of Windows PowerShell:
+   ```powershell
+   pwsh
+   cd path\to\openhands
+   $env:RUNTIME="local"; poetry run uvicorn openhands.server.listen:app --host 0.0.0.0 --port 3000 --reload --reload-exclude "./workspace"
+   ```
+
+   > **Note**: Make sure you're explicitly using `pwsh` (PowerShell 7) and not `powershell` (Windows PowerShell). The command prompt or terminal title should say "PowerShell 7" rather than just "Windows PowerShell".
+
+5. **If the issue persists**, ensure that you have the .NET Runtime installed:
+   - Download and install the latest .NET Runtime from [Microsoft's .NET download page](https://dotnet.microsoft.com/download)
+   - Choose ".NET Runtime" (not SDK) version 6.0 or later
+   - After installation, verify it's properly installed by running:
+     ```powershell
+     dotnet --info
+     ```
+   - Restart your computer after installation
+   - Try running OpenHands again
+
+6. **Ensure that the .NET Framework is properly installed** on your system:
+   - Go to Control Panel > Programs > Programs and Features > Turn Windows features on or off
+   - Make sure ".NET Framework 4.8 Advanced Services" is enabled
+   - Click OK and restart if prompted
+
+This error occurs because OpenHands uses the pythonnet package to interact with PowerShell, which requires the System.Management.Automation assembly from the .NET framework. A minimal PowerShell installation or older Windows PowerShell (rather than PowerShell 7+) might not include all the necessary components for this integration.

evaluation/README.md

@@ -71,10 +71,27 @@ EVAL_CONDENSER=summarizer_for_eval \
 The name is up to you, but should match a name defined in your `config.toml` file. The last argument in the command specifies the condenser configuration to use. In this case, `summarizer_for_eval` is used, which refers to the LLM-based summarizing condenser as defined above.
 
 If no condenser configuration is specified, the 'noop' condenser will be used by default, which keeps the full conversation history.
-```
 
 For other configurations specific to evaluation, such as `save_trajectory_path`, these are typically set in the `get_config` function of the respective `run_infer.py` file for each benchmark.
 
+### Enabling LLM-Based Editor Tools
+
+The LLM-Based Editor tool (currently supported only for SWE-Bench) can be enabled by setting:
+```bash
+export ENABLE_LLM_EDITOR=true
+```
+
+You can set the config for the Editor LLM as:
+```toml
+[llm.draft_editor]
+base_url = "http://localhost:9002/v1"
+model = "hosted_vllm/lite_coder_qwen_editor_3B"
+api_key = ""
+temperature = 0.7
+max_input_tokens = 10500
+max_output_tokens = 10500
+```
+
 ## Supported Benchmarks
 
 The OpenHands evaluation harness supports a wide variety of benchmarks across [software engineering](#software-engineering), [web browsing](#web-browsing), [miscellaneous assistance](#misc-assistance), and [real-world](#real-world) tasks.

evaluation/benchmarks/browsing_delegation/run_infer.py

@@ -144,7 +144,7 @@ if __name__ == '__main__':
     llm_config = None
     if args.llm_config:
         llm_config = get_llm_config_arg(args.llm_config)
-        # modify_params must be False for evaluation purpose, for reproducibility and accurancy of results
+        # modify_params must be False for evaluation purpose, for reproducibility and accuracy of results
         llm_config.modify_params = False
 
     if llm_config is None:

evaluation/benchmarks/gaia/.gitignore

@@ -0,0 +1 @@
+data/

evaluation/benchmarks/gaia/README.md

@@ -6,6 +6,13 @@ This folder contains evaluation harness for evaluating agents on the [GAIA bench
 
 Please follow instruction [here](../../README.md#setup) to setup your local development environment and LLM.
 
+To enable the Tavily MCP Server, you can add the Tavily API key under the `core` section of your `config.toml` file, like below:
+
+```toml
+[core]
+search_api_key = "tvly-******"
+```
+
 ## Run the evaluation
 
 We are using the GAIA dataset hosted on [Hugging Face](https://huggingface.co/datasets/gaia-benchmark/GAIA).

evaluation/benchmarks/gaia/run_infer.py

@@ -1,13 +1,22 @@
 import asyncio
+import copy
 import functools
 import os
 import re
+import shutil
+import zipfile
 
 import huggingface_hub
 import pandas as pd
 from datasets import load_dataset
+from PIL import Image
+from pydantic import SecretStr
 
 from evaluation.benchmarks.gaia.scorer import question_scorer
+from evaluation.benchmarks.gaia.utils import (
+    image_to_jpg_base64_url,
+    image_to_png_base64_url,
+)
 from evaluation.utils.shared import (
     EvalMetadata,
     EvalOutput,
@@ -24,6 +33,7 @@ from openhands.core.config import (
     OpenHandsConfig,
     get_llm_config_arg,
     get_parser,
+    load_from_toml,
 )
 from openhands.core.config.utils import get_agent_config_arg
 from openhands.core.logger import openhands_logger as logger
@@ -41,7 +51,7 @@ AGENT_CLS_TO_FAKE_USER_RESPONSE_FN = {
 }
 
 AGENT_CLS_TO_INST_SUFFIX = {
-    'CodeActAgent': 'When you think you have solved the question, please first send your answer to user through message and then exit.\n'
+    'CodeActAgent': 'When you think you have solved the question, please use the finish tool and include your final answer in the message parameter of the finish tool. Your final answer MUST be encapsulated within <solution> and </solution>.\n'
 }
 
 
@@ -49,7 +59,7 @@ def get_config(
     metadata: EvalMetadata,
 ) -> OpenHandsConfig:
     sandbox_config = get_default_sandbox_config_for_eval()
-    sandbox_config.base_container_image = 'python:3.12-bookworm'
+    sandbox_config.base_container_image = 'nikolaik/python-nodejs:python3.12-nodejs22'
     config = OpenHandsConfig(
         default_agent=metadata.agent_class,
         run_as_openhands=False,
@@ -67,6 +77,11 @@ def get_config(
         logger.info('Agent config not provided, using default settings')
         agent_config = config.get_agent_config(metadata.agent_class)
         agent_config.enable_prompt_extensions = False
+
+    config_copy = copy.deepcopy(config)
+    load_from_toml(config_copy)
+    if config_copy.search_api_key:
+        config.search_api_key = SecretStr(config_copy.search_api_key)
     return config
 
 
@@ -89,27 +104,44 @@ def initialize_runtime(
     if instance['file_name'] != '':
         # if this question comes with a file, we need to save it to the workspace
         assert metadata.data_split is not None
+        extension_name = instance['file_name'].split('.')[-1]
         src_file = os.path.join(
             DATASET_CACHE_DIR, '2023', metadata.data_split, instance['file_name']
         )
         assert os.path.exists(src_file)
-        dest_file = os.path.join('/workspace', instance['file_name'])
-        runtime.copy_to(src_file, dest_file)
+        if extension_name == 'zip':
+            temp_dir = os.path.join(
+                DATASET_CACHE_DIR, '2023', metadata.data_split, 'tmp_file'
+            )
+            os.makedirs(temp_dir, exist_ok=True)
+            with zipfile.ZipFile(src_file, 'r') as zip_ref:
+                zip_ref.extractall(temp_dir)
+            for root, dirs, files in os.walk(temp_dir):
+                for file in files:
+                    dest_file = '/workspace'
+                    runtime.copy_to(os.path.join(root, file), dest_file)
+            shutil.rmtree(temp_dir)
+        elif extension_name not in ['jpg', 'png']:
+            dest_file = '/workspace'
+            runtime.copy_to(src_file, dest_file)
 
-        # rename to file.extension_name
-        extension_name = instance['file_name'].split('.')[-1]
-        action = CmdRunAction(
-            command=f'mv /workspace/{instance["file_name"]} /workspace/file.{extension_name}'
-        )
-        logger.info(action, extra={'msg_type': 'ACTION'})
-        obs = runtime.run_action(action)
-        assert obs.exit_code == 0
+            # rename to file.extension_name
+            action = CmdRunAction(
+                command=f'mv /workspace/{instance["file_name"]} /workspace/file.{extension_name}'
+            )
+            logger.info(action, extra={'msg_type': 'ACTION'})
+            obs = runtime.run_action(action)
+            assert obs.exit_code == 0
 
     action = CmdRunAction(command='cd /workspace')
     logger.info(action, extra={'msg_type': 'ACTION'})
     obs = runtime.run_action(action)
     assert obs.exit_code == 0
 
+    action = CmdRunAction(
+        command='apt-get update && apt-get install -y ffmpeg && apt-get install -y ffprobe'
+    )
+    runtime.run_action(action)
     logger.info(f'{"-" * 50} END Runtime Initialization Fn {"-" * 50}')
 
 
@@ -134,16 +166,49 @@ def process_instance(
         dest_file = None
 
     # Prepare instruction
-    instruction = f'{instance["Question"]}\n'
+    instruction = """You have one question to answer. It is paramount that you provide a correct answer.
+Give it all you can: I know for a fact that you have access to all the relevant tools to solve it and find the correct answer (the answer does exist). Failure or 'I cannot answer' or 'None found' will not be tolerated, success will be rewarded.
+You must make sure you find the correct answer! You MUST strictly follow the task-specific formatting instructions for your final answer.
+Here is the task:
+{task_question}
+""".format(
+        task_question=instance['Question'],
+    )
     logger.info(f'Instruction: {instruction}')
+    image_urls = []
     if dest_file:
-        instruction += f'\n\nThe mentioned file is provided in the workspace at: {dest_file.split("/")[-1]}'
+        if extension_name not in ['jpg', 'png', 'zip']:
+            instruction += f'To solve this task you will have to use the attached file provided in the workspace at location: {dest_file}\n\n'
+        elif extension_name == 'zip':
+            filenames = []
+            src_file = os.path.join(
+                DATASET_CACHE_DIR, '2023', metadata.data_split, instance['file_name']
+            )
+            with zipfile.ZipFile(src_file, 'r') as zip_ref:
+                filenames = zip_ref.namelist()
 
-    instruction += 'IMPORTANT: You should ONLY interact with the environment provided to you AND NEVER ASK FOR HUMAN HELP.\n'
-    instruction += 'Please encapsulate your final answer (answer ONLY) within <solution> and </solution>.\n'
+            filenames = [f'/workspace/{file}' for file in filenames]
+            filenames = ', '.join(filenames)
+            instruction += f'To solve this task you will have to use the attached files provided in the workspace at locations: {filenames}\n\n'
+        else:  # Image files: jpg, png
+            src_file = os.path.join(
+                DATASET_CACHE_DIR, '2023', metadata.data_split, instance['file_name']
+            )
+            instruction += 'Image: To solve this task you will have to use the image shown below.\n\n'
+            image = Image.open(src_file)
+            if extension_name == 'jpg':
+                image_urls.append(image_to_jpg_base64_url(image))
+            else:
+                image_urls.append(image_to_png_base64_url(image))
+
+    instruction += """IMPORTANT: When seeking information from a website, REFRAIN from arbitrary URL navigation. You should utilize the designated search engine tool with precise keywords to obtain relevant URLs or use the specific website's search interface. DO NOT navigate directly to specific URLs as they may not exist.\n\nFor example: if you want to search for a research paper on Arxiv, either use the search engine tool with specific keywords or navigate to arxiv.org and then use its interface.\n"""
+    instruction += 'IMPORTANT: You should NEVER ask for Human Help.\n'
+    instruction += 'IMPORTANT: Please encapsulate your final answer (answer ONLY) within <solution> and </solution>. Your answer will be evaluated using string matching approaches so it important that you STRICTLY adhere to the output formatting instructions specified in the task (e.g., alphabetization, sequencing, units, rounding, decimal places, etc.)\n'
     instruction += (
         'For example: The answer to the question is <solution> 42 </solution>.\n'
     )
+    instruction += "IMPORTANT: Your final answer should be a number OR as few words as possible OR a comma separated list of numbers and/or strings. If you are asked for a number, express it numerically (i.e., with digits rather than words), do not use commas, and do not include units such as $ or percent signs unless specified otherwise. If you are asked for a string, don't use articles, neither abbreviations (e.g. for cities). If you are asked for a comma separated list, apply the above rules depending of whether the element to be put in the list is a number or a string.\n"
+
     # NOTE: You can actually set slightly different instruction for different agents
     instruction += AGENT_CLS_TO_INST_SUFFIX.get(metadata.agent_class, '')
     logger.info(f'Instruction:\n{instruction}', extra={'msg_type': 'OBSERVATION'})
@@ -156,7 +221,9 @@ def process_instance(
     state: State | None = asyncio.run(
         run_controller(
             config=config,
-            initial_user_action=MessageAction(content=instruction),
+            initial_user_action=MessageAction(
+                content=instruction, image_urls=image_urls
+            ),
             runtime=runtime,
             fake_user_response_fn=AGENT_CLS_TO_FAKE_USER_RESPONSE_FN[
                 metadata.agent_class
@@ -175,7 +242,7 @@ def process_instance(
     for event in reversed(state.history):
         if event.source == 'agent':
             if isinstance(event, AgentFinishAction):
-                model_answer_raw = event.thought
+                model_answer_raw = event.final_thought
                 break
             elif isinstance(event, CmdRunAction):
                 model_answer_raw = event.thought
@@ -222,6 +289,7 @@ def process_instance(
         error=state.last_error if state and state.last_error else None,
         test_result=test_result,
     )
+    runtime.close()
     return output
 
 
@@ -253,6 +321,8 @@ if __name__ == '__main__':
     if llm_config is None:
         raise ValueError(f'Could not find LLM config: --llm_config {args.llm_config}')
 
+    toml_config = OpenHandsConfig()
+    load_from_toml(toml_config)
     metadata = make_metadata(
         llm_config=llm_config,
         dataset_name='gaia',
@@ -261,7 +331,10 @@ if __name__ == '__main__':
         eval_note=args.eval_note,
         eval_output_dir=args.eval_output_dir,
         data_split=args.data_split,
-        details={'gaia-level': args.level},
+        details={
+            'gaia-level': args.level,
+            'mcp-servers': ['tavily'] if toml_config.search_api_key else [],
+        },
         agent_config=agent_config,
     )
 

evaluation/benchmarks/gaia/scripts/run_infer.sh

@@ -39,7 +39,7 @@ echo "LEVELS: $LEVELS"
 COMMAND="poetry run python ./evaluation/benchmarks/gaia/run_infer.py \
   --agent-cls $AGENT \
   --llm-config $MODEL_CONFIG \
-  --max-iterations 30 \
+  --max-iterations 60 \
   --level $LEVELS \
   --data-split validation \
   --eval-num-workers $NUM_WORKERS \

evaluation/benchmarks/gaia/utils.py

@@ -0,0 +1,43 @@
+import base64
+import io
+
+import numpy as np
+from PIL import Image
+
+
+def image_to_png_base64_url(
+    image: np.ndarray | Image.Image, add_data_prefix: bool = True
+):
+    """Convert a numpy array to a base64 encoded png image url."""
+    if isinstance(image, np.ndarray):
+        image = Image.fromarray(image)
+    if image.mode in ('RGBA', 'LA'):
+        image = image.convert('RGB')
+    buffered = io.BytesIO()
+    image.save(buffered, format='PNG')
+
+    image_base64 = base64.b64encode(buffered.getvalue()).decode()
+    return (
+        f'data:image/png;base64,{image_base64}'
+        if add_data_prefix
+        else f'{image_base64}'
+    )
+
+
+def image_to_jpg_base64_url(
+    image: np.ndarray | Image.Image, add_data_prefix: bool = True
+):
+    """Convert a numpy array to a base64 encoded jpeg image url."""
+    if isinstance(image, np.ndarray):
+        image = Image.fromarray(image)
+    if image.mode in ('RGBA', 'LA'):
+        image = image.convert('RGB')
+    buffered = io.BytesIO()
+    image.save(buffered, format='JPEG')
+
+    image_base64 = base64.b64encode(buffered.getvalue()).decode()
+    return (
+        f'data:image/jpeg;base64,{image_base64}'
+        if add_data_prefix
+        else f'{image_base64}'
+    )