Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Update documentation with updated information from releases (#8331)

mamoodi6f88ddb2abfc
diff --git a/docs/README.md b/docs/README.md
index ded03b677c..eed11fe822 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,37 +4,32 @@ This website is built using [Docusaurus](https://docusaurus.io/).
When published, the content will be published at https://docs.all-hands.dev/.
-### Installation
+### Local Development
```bash
$ cd docs
-$ yarn
+$ npm install
+$ npm run start
```
-### Local Development
-
-```
-$ yarn start # for the default English version
-```
-
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+This command starts a local development server and opens up a browser window.
+Most changes are reflected live without having to restart the server.
Alternatively, you can pass a `--locale` argument to render a specific language in dev mode as in:
```
-$ yarn start --locale pt-BR # for the Brazilian Portuguese version
-$ yarn start --locale fr # for the French version
-$ yarn start --locale zh-Hans # for the Chinese Han (simplified variant) version
+$ npm run start --locale pt-BR # for the Brazilian Portuguese version
+$ npm run start --locale fr # for the French version
+$ npm run start --locale zh-Hans # for the Chinese Han (simplified variant) version
```
### Build
```
-$ yarn build
+$ npm run build
```
This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
It compiles all languages.
### Deployment
diff --git a/docs/modules/usage/cloud/_category_.json b/docs/modules/usage/cloud/_category_.json
deleted file mode 100644
index 91b8bb67d0..0000000000
--- a/docs/modules/usage/cloud/_category_.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
- "label": "OpenHands Cloud",
- "position": 9,
- "link": {
- "type": "generated-index",
- "description": "Documentation for OpenHands Cloud features and services."
- }
-}
diff --git a/docs/modules/usage/cloud/cloud-api.md b/docs/modules/usage/cloud/cloud-api.md
index 09a3a8b660..f7a5630b28 100644
--- a/docs/modules/usage/cloud/cloud-api.md
+++ b/docs/modules/usage/cloud/cloud-api.md
@@ -1,6 +1,7 @@
# OpenHands Cloud API
-OpenHands Cloud provides a REST API that allows you to programmatically interact with the service. This is useful if you easily want to kick off your own jobs from your programs in a flexible way.
+OpenHands Cloud provides a REST API that allows you to programmatically interact with the service. This is useful if
+you want to kick off your own jobs from your programs in a flexible way.
This guide explains how to obtain an API key and use the API to start conversations.
For more detailed information about the API, refer to the [OpenHands API Reference](https://docs.all-hands.dev/swagger-ui/).
@@ -9,12 +10,12 @@ For more detailed information about the API, refer to the [OpenHands API Referen
To use the OpenHands Cloud API, you'll need to generate an API key:
-1. Log in to your [OpenHands Cloud](https://app.all-hands.dev) account
-2. Navigate to the [Settings page](https://app.all-hands.dev/settings)
-3. Locate the "API Keys" section
-4. Click "Generate New Key"
-5. Give your key a descriptive name (e.g., "Development", "Production")
-6. Copy the generated API key and store it securely - it will only be shown once
+1. Log in to your [OpenHands Cloud](https://app.all-hands.dev) account.
+2. Navigate to the [Settings page](https://app.all-hands.dev/settings).
+3. Select the `API Keys` tab.
+4. Click `Create API Key`.
+5. Give your key a descriptive name (Example: "Development" or "Production") and select `Create`.
+6. Copy the generated API key and store it securely. It will only be shown once.
![API Key Generation](/img/docs/api-key-generation.png)
@@ -22,14 +23,14 @@ To use the OpenHands Cloud API, you'll need to generate an API key:
### Starting a New Conversation
-To start a new conversation with OpenHands performing a task, you'll need to make a POST request to the conversation endpoint.
+To start a new conversation with OpenHands to perform a task, you'll need to make a POST request to the conversation endpoint.
#### Request Parameters
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `initial_user_msg` | string | Yes | The initial message to start the conversation |
-| `repository` | string | No | Git repository name to provide context in the format `owner/repo`. You must have access to the repo. |
+| Parameter | Type | Required | Description |
+|--------------------|----------|----------|------------------------------------------------------------------------------------------------------|
+| `initial_user_msg` | string | Yes | The initial message to start the conversation. |
+| `repository` | string | No | Git repository name to provide context in the format `owner/repo`. You must have access to the repo. |
#### Examples
@@ -126,11 +127,11 @@ The API will return a JSON object with details about the created conversation:
}
```
-You may also receive an `AuthenticationError` if:
+You may receive an `AuthenticationError` if:
-1. You provided an invalid API key
-2. You provided the wrong repo name
-3. You don't have access to the repo
+- You provided an invalid API key.
+- You provided the wrong repository name.
+- You don't have access to the repository.
### Retrieving Conversation Status
diff --git a/docs/modules/usage/cloud/openhands-cloud.mdx b/docs/modules/usage/cloud/openhands-cloud.mdx
index 9a95b25e9a..bd7dcdd3e0 100644
--- a/docs/modules/usage/cloud/openhands-cloud.mdx
+++ b/docs/modules/usage/cloud/openhands-cloud.mdx
@@ -60,6 +60,6 @@ When using your GitLab account, OpenHands will automatically have access to your
## Conversation Persistence
-- Conversations List – Displays only the 10 most recent conversations initiated within the past 10 days.
+- Conversations List – Displays only the 20 most recent conversations initiated within the past 10 days.
- Workspaces – Conversation workspaces are retained for 14 days.
- Runtimes – Runtimes remain active ("warm") for 30 minutes. After this period, resuming a conversation may take 1–2 minutes.
diff --git a/docs/modules/usage/how-to/gui-mode.md b/docs/modules/usage/how-to/gui-mode.md
index 45810bd5a7..187406808f 100644
--- a/docs/modules/usage/how-to/gui-mode.md
+++ b/docs/modules/usage/how-to/gui-mode.md
@@ -122,7 +122,7 @@ OpenHands automatically exports a `GITLAB_TOKEN` to the shell environment if pro
### Advanced Settings
-1. Inside the Settings page, toggle `Advanced` options to access additional settings.
+1. Inside the Settings page, under the `LLM` tab, toggle `Advanced` options to access additional settings.
2. Use the `Custom Model` text box to manually enter a model if it's not in the list.
3. Specify a `Base URL` if required by your LLM provider.
diff --git a/docs/modules/usage/installation.mdx b/docs/modules/usage/installation.mdx
index fac0e4cd68..adbe22f4b8 100644
--- a/docs/modules/usage/installation.mdx
+++ b/docs/modules/usage/installation.mdx
@@ -84,8 +84,8 @@ After launching OpenHands, you **must** select an `LLM Provider` and `LLM Model`
This can be done during the initial settings popup or by selecting the `Settings`
button (gear icon) in the UI.
-If the required model does not exist in the list, you can toggle `Advanced` options and manually enter it with the correct prefix
-in the `Custom Model` text box.
+If the required model does not exist in the list, in `Settings` under the `LLM` tab, you can toggle `Advanced` options
+and manually enter it with the correct prefix in the `Custom Model` text box.
The `Advanced` options also allow you to specify a `Base URL` if required.
### Getting an API Key
diff --git a/docs/modules/usage/runtimes/docker.md b/docs/modules/usage/runtimes/docker.md
index 8a1e33de9b..d1ddba8626 100644
--- a/docs/modules/usage/runtimes/docker.md
+++ b/docs/modules/usage/runtimes/docker.md
@@ -21,40 +21,36 @@ docker run # ...
# ...
```
-The `SANDBOX_VOLUMES` format is: `host_path:container_path[:mode]`
+The `SANDBOX_VOLUMES` format is `host_path:container_path[:mode]` where:
-- `host_path`: The path on your host machine that you want to mount
-- `container_path`: The path inside the container where the host path will be mounted
+- `host_path`: The path on your host machine that you want to mount.
+- `container_path`: The path inside the container where the host path will be mounted.
- Use `/workspace` for files you want the agent to modify. The agent works in `/workspace` by default.
- - Use a different path (e.g., `/data`) for read-only reference materials or large datasets
-- `mode`: Optional mount mode, either `rw` (read-write, default) or `ro` (read-only)
+ - Use a different path (e.g., `/data`) for read-only reference materials or large datasets.
+- `mode`: Optional mount mode, either `rw` (read-write, default) or `ro` (read-only).
You can also specify multiple mounts by separating them with commas (`,`):
```bash
-export SANDBOX_VOLUMES=/path1:/workspace/path1,/path2:/workspace/path2:ro
+-e SANDBOX_VOLUMES=/path1:/workspace/path1,/path2:/workspace/path2:ro
```
Examples:
```bash
# Linux and Mac Example - Writable workspace
-export SANDBOX_VOLUMES=$HOME/OpenHands:/workspace:rw
+-e SANDBOX_VOLUMES=$HOME/OpenHands:/workspace:rw
# WSL on Windows Example - Writable workspace
-export SANDBOX_VOLUMES=/mnt/c/dev/OpenHands:/workspace:rw
+-e SANDBOX_VOLUMES=/mnt/c/dev/OpenHands:/workspace:rw
# Read-only reference code example
-export SANDBOX_VOLUMES=/path/to/reference/code:/data:ro
+-e SANDBOX_VOLUMES=/path/to/reference/code:/data:ro
# Multiple mounts example - Writable workspace with read-only reference data
-export SANDBOX_VOLUMES=$HOME/projects:/workspace:rw,/path/to/large/dataset:/data:ro
+-e SANDBOX_VOLUMES=$HOME/projects:/workspace:rw,/path/to/large/dataset:/data:ro
```
-> **Note:** When using multiple mounts, the first mount is considered the primary workspace and will be used for backward compatibility with tools that expect a single workspace.
-
-> **Important:** The agent will work in `/workspace` by default. If you want the agent to modify files in your local directory, you should mount that directory to `/workspace`. If you have read-only data that you want the agent to access but not modify, mount it to a different path (like `/data`) and explicitly instruct the agent to look there.
-
### Using WORKSPACE_* variables (Deprecated)
> **Note:** This method is deprecated and will be removed in a future version. Please use `SANDBOX_VOLUMES` instead.
diff --git a/docs/modules/usage/troubleshooting/troubleshooting.md b/docs/modules/usage/troubleshooting/troubleshooting.md
index b879e0c548..f69e8812c1 100644
--- a/docs/modules/usage/troubleshooting/troubleshooting.md
+++ b/docs/modules/usage/troubleshooting/troubleshooting.md
@@ -4,38 +4,6 @@
OpenHands only supports Windows via WSL. Please be sure to run all commands inside your WSL terminal.
:::
-### Unable to access VS Code tab via local IP
-
-**Description**
-
-When accessing OpenHands through a non-localhost URL (such as a LAN IP address), the VS Code tab shows a "Forbidden" error, while other parts of the UI work fine.
-
-**Resolution**
-
-This happens because VS Code runs on a random high port that may not be exposed or accessible from other machines. To fix this:
-
-1. Set a specific port for VS Code using the `SANDBOX_VSCODE_PORT` environment variable:
- ```bash
- docker run -it --rm \
- -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 \
- -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
- ```
-
-2. Make sure to expose the same port with `-p 41234:41234` in your Docker command.
-
-3. Alternatively, you can set this in your `config.toml` file:
- ```toml
- [sandbox]
- vscode_port = 41234
- ```
-
### Launch docker client failed
**Description**
@@ -67,3 +35,35 @@ On initial prompt, an error is seen with `Permission Denied` or `PermissionError
* 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.
+
+### Unable to access VS Code tab via local IP
+
+**Description**
+
+When accessing OpenHands through a non-localhost URL (such as a LAN IP address), the VS Code tab shows a "Forbidden"
+error, while other parts of the UI work fine.
+
+**Resolution**
+
+This happens because VS Code runs on a random high port that may not be exposed or accessible from other machines.
+To fix this:
+
+1. Set a specific port for VS Code using the `SANDBOX_VSCODE_PORT` environment variable:
+ ```bash
+ docker run -it --rm \
+ -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 \
+ -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
+ ```
+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
+ [sandbox]
+ vscode_port = 41234
+ ```