github/OpenHands
1
0
Fork 0
mirror of https://github.com/OpenHands/OpenHands.git synced 2025-12-26 05:48:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation with updated information from releases (#8331)

Browse Source
This commit is contained in:
mamoodi 2025-05-08 11:09:01 -04:00 committed by GitHub
parent 750b1f03b7
commit 6f88ddb2ab
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 72 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/README.md
View File

@ -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

8
docs/modules/usage/cloud/_category_.json
View File

@ -1,8 +0,0 @@
{
"label": "OpenHands Cloud",
"position": 9,
"link": {
"type": "generated-index",
"description": "Documentation for OpenHands Cloud features and services."
}
}

33
docs/modules/usage/cloud/cloud-api.md
View File

@ -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

2
docs/modules/usage/cloud/openhands-cloud.mdx
View File

@ -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.

2
docs/modules/usage/how-to/gui-mode.md
View File

@ -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.

4
docs/modules/usage/installation.mdx
View File

@ -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

24
docs/modules/usage/runtimes/docker.md
View File

@ -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.

64
docs/modules/usage/troubleshooting/troubleshooting.md
View File

@ -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
```