mirror of
https://github.com/OpenHands/OpenHands.git
synced 2025-12-26 05:48:36 +08:00
docs: Update documentation with some consistency (#2706)
* Update documentation with some consistency * Make windows troubleshooting a little more clear * Apply suggestions from code review Co-authored-by: Boxuan Li <liboxuan@connect.hku.hk> --------- Co-authored-by: Mahmoud Work <mahmoudwork@mahmouds-mini.home> Co-authored-by: Boxuan Li <liboxuan@connect.hku.hk>
This commit is contained in:
mamoodi
GitHub
parent
8dae1f9307
commit
00542432bd
@ -29,7 +29,7 @@ For details, please check [this document](https://github.com/OpenDevin/OpenDevin
|
||||
|
||||
## 🤖 Join Our Community
|
||||
|
||||
Now we have both Slack workspace for the collaboration on building OpenDevin and Discord server for discussion about anything related, e.g., this project, LLM, agent, etc.
|
||||
We have both Slack workspace for the collaboration on building OpenDevin and Discord server for discussion about anything related, e.g., this project, LLM, agent, etc.
|
||||
|
||||
- [Slack workspace](https://join.slack.com/t/opendevin/shared_invite/zt-2jsrl32uf-fTeeFjNyNYxqSZt5NPY3fA)
|
||||
- [Discord server](https://discord.gg/ESHStjSjD4)
|
||||
|
||||
@ -57,11 +57,6 @@ _Example of CodeActAgent with `gpt-4-turbo-2024-04-09` performing a data science
|
||||
| `step` | Performs one step using the CodeAct Agent. This includes gathering info on previous steps and prompting the model to make a command to execute. |
|
||||
| `search_memory` | Not yet implemented |
|
||||
|
||||
### Work-in-progress & Next step
|
||||
|
||||
[] Support web-browsing
|
||||
[] Complete the workflow for CodeAct agent to submit Github PRs
|
||||
|
||||
## Monologue Agent
|
||||
|
||||
### Description
|
||||
|
||||
@ -8,7 +8,7 @@ This is a high-level overview of the system architecture. The system is divided
|
||||
|
||||
|
||||
|
||||
This Overview is simplified to show the main components and their interactions. For a more detailed view of the backend architecture, see the [Backend Architecture](#backend-architecture-en) section.
|
||||
This Overview is simplified to show the main components and their interactions. For a more detailed view of the backend architecture, see the Backend Architecture section below.
|
||||
|
||||
# Backend Architecture {#backend-architecture-en}
|
||||
|
||||
|
||||
@ -4,17 +4,7 @@ The default OpenDevin sandbox comes with a [minimal ubuntu configuration](https:
|
||||
|
||||
## Setup
|
||||
|
||||
To get started running with your own Docker Sandbox image you need to ensure you can build OpenDevin locally via the following:
|
||||
1. Clone the OpenDevin github repository to your local machine
|
||||
2. In the root (OpenDevin/) directory, run ```make build```
|
||||
3. Then run ```make run```
|
||||
4. Finally navigate your browser to ```localhost:3001``` to ensure that your local build of OpenDevin is functional
|
||||
|
||||
|
||||
Please refer to [Development.md](https://github.com/OpenDevin/OpenDevin/blob/main/Development.md) for more installation details.
|
||||
|
||||
> Note that the above steps will take some time to run and will require that your have python3.11, poetry (a python package manager), and Docker installed
|
||||
|
||||
Make sure you are able to run OpenDevin using the [Development.md](https://github.com/OpenDevin/OpenDevin/blob/main/Development.md) first.
|
||||
|
||||
## Create Your Docker Image
|
||||
|
||||
@ -34,9 +24,9 @@ Next build your docker image with the name of your choice, for example "custom_i
|
||||
|
||||
This will produce a new image called ```custom_image``` that will be available in Docker Engine.
|
||||
|
||||
> Note that in the configuration described in this document, OpenDevin will run as user "opendevin" inside the sandbox and thus all packages installed via the docker file should be available to all users on the system, not just root
|
||||
> Note that in the configuration described in this document, OpenDevin will run as user "opendevin" inside the sandbox and thus all packages installed via the docker file should be available to all users on the system, not just root.
|
||||
>
|
||||
> Installing with apt-get above installs node for all users
|
||||
> Installing with apt-get above installs node for all users.
|
||||
|
||||
|
||||
## Specify your custom image in config.toml file
|
||||
@ -50,11 +40,10 @@ persist_sandbox=false
|
||||
run_as_devin=true
|
||||
sandbox_container_image="custom_image"
|
||||
```
|
||||
> Ensure that sandbox_container_image is set to the name of your custom image from the previous step
|
||||
> Ensure that sandbox_container_image is set to the name of your custom image from the previous step.
|
||||
|
||||
## Run
|
||||
Run OpenDevin by running ```make run``` in the top level directory.
|
||||
A lot of things will happen but ultimately the OpenDevin server and frontend should be running.
|
||||
|
||||
Navigate to ```localhost:3001``` and check if your desired dependencies are available.
|
||||
|
||||
@ -85,10 +74,7 @@ dockerfile_content = (
|
||||
).strip()
|
||||
```
|
||||
|
||||
> Note: the name of the image is modified via [_get_new_image_name()](https://github.com/OpenDevin/OpenDevin/blob/main/opendevin/runtime/docker/image_agnostic_util.py#L63) and it is the modified name that is searched for on subsequent runs
|
||||
|
||||
|
||||
|
||||
> Note: the name of the image is modified via [_get_new_image_name()](https://github.com/OpenDevin/OpenDevin/blob/main/opendevin/runtime/docker/image_agnostic_util.py#L63) and it is the modified name that is searched for on subsequent runs.
|
||||
|
||||
## Troubleshooting / Errors
|
||||
|
||||
|
||||
@ -13,8 +13,7 @@ OpenDevin will issue many prompts to the LLM you configure. Most of these LLMs c
|
||||
:::
|
||||
|
||||
The `LLM_MODEL` environment variable controls which model is used in programmatic interactions.
|
||||
But when using the OpenDevin UI, you'll need to choose your model in the settings window (the gear
|
||||
wheel on the bottom left).
|
||||
But when using the OpenDevin UI, you'll need to choose your model in the settings window.
|
||||
|
||||
The following environment variables might be necessary for some LLMs:
|
||||
|
||||
|
||||
@ -19,11 +19,19 @@ open a *PR* to add details to this file.
|
||||
If you're running on Windows and having trouble, check out our [guide for Windows (WSL) users](troubleshooting/windows).
|
||||
:::
|
||||
|
||||
## Unable to connect to Docker
|
||||
## Common Issues
|
||||
|
||||
* [Unable to connect to Docker](#unable-to-connect-to-docker)
|
||||
* [Unable to connect to SSH box](#unable-to-connect-to-ssh-box)
|
||||
* [404 Resource not found](#404-resource-not-found)
|
||||
* [`make build` getting stuck on package installations](#make-build-getting-stuck-on-package-installations)
|
||||
* [Sessions are not restored](#sessions-are-not-restored)
|
||||
|
||||
### Unable to connect to Docker
|
||||
|
||||
[GitHub Issue](https://github.com/OpenDevin/OpenDevin/issues/1226)
|
||||
|
||||
### Symptoms
|
||||
**Symptoms**
|
||||
|
||||
```bash
|
||||
Error creating controller. Please check Docker is running and visit `https://opendevin.github.io/OpenDevin/modules/usage/troubleshooting` for more debugging information.
|
||||
@ -33,22 +41,23 @@ Error creating controller. Please check Docker is running and visit `https://ope
|
||||
docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
|
||||
```
|
||||
|
||||
### Details
|
||||
**Details**
|
||||
|
||||
OpenDevin uses a Docker container to do its work safely, without potentially breaking your machine.
|
||||
|
||||
### Workarounds
|
||||
**Workarounds**
|
||||
|
||||
* Run `docker ps` to ensure that docker is running
|
||||
* Make sure you don't need `sudo` to run docker [see here](https://www.baeldung.com/linux/docker-run-without-sudo)
|
||||
* If you are on a Mac, check the [permissions requirements](https://docs.docker.com/desktop/mac/permission-requirements/) and in particular consider enabling the `Allow the default Docker socket to be used` under `Settings > Advanced` in Docker Desktop.
|
||||
* In addition, upgrade your Docker to the latest version under `Check for Updates`
|
||||
|
||||
## Unable to connect to SSH box
|
||||
---
|
||||
### Unable to connect to SSH box
|
||||
|
||||
[GitHub Issue](https://github.com/OpenDevin/OpenDevin/issues/1156)
|
||||
|
||||
### Symptoms
|
||||
**Symptoms**
|
||||
|
||||
```python
|
||||
self.shell = DockerSSHBox(
|
||||
@ -56,12 +65,12 @@ self.shell = DockerSSHBox(
|
||||
pexpect.pxssh.ExceptionPxssh: Could not establish connection to host
|
||||
```
|
||||
|
||||
### Details
|
||||
**Details**
|
||||
|
||||
By default, OpenDevin connects to a running container using SSH. On some machines,
|
||||
especially Windows, this seems to fail.
|
||||
|
||||
### Workarounds
|
||||
**Workarounds**
|
||||
|
||||
* Restart your computer (sometimes it does work)
|
||||
* Be sure to have the latest versions of WSL and Docker
|
||||
@ -69,11 +78,12 @@ especially Windows, this seems to fail.
|
||||
* Try [this reinstallation guide](https://github.com/OpenDevin/OpenDevin/issues/1156#issuecomment-2064549427)
|
||||
* Set `-e SANDBOX_TYPE=exec` to switch to the ExecBox docker container
|
||||
|
||||
## Unable to connect to LLM
|
||||
---
|
||||
### Unable to connect to LLM
|
||||
|
||||
[GitHub Issue](https://github.com/OpenDevin/OpenDevin/issues/1208)
|
||||
|
||||
### Symptoms
|
||||
**Symptoms**
|
||||
|
||||
```python
|
||||
File "/app/.venv/lib/python3.12/site-packages/openai/_exceptions.py", line 81, in __init__
|
||||
@ -82,22 +92,23 @@ especially Windows, this seems to fail.
|
||||
AttributeError: 'NoneType' object has no attribute 'request'
|
||||
```
|
||||
|
||||
### Details
|
||||
**Details**
|
||||
|
||||
[GitHub Issues](https://github.com/OpenDevin/OpenDevin/issues?q=is%3Aissue+is%3Aopen+404)
|
||||
|
||||
This usually happens with *local* LLM setups, when OpenDevin can't connect to the LLM server.
|
||||
See our guide for [local LLMs](llms/localLLMs) for more information.
|
||||
|
||||
### Workarounds
|
||||
**Workarounds**
|
||||
|
||||
* Check your `base_url` in your config.toml (if it exists) under the "llm" section
|
||||
* Check that ollama (or whatever LLM you're using) is running OK
|
||||
* Make sure you're using `--add-host host.docker.internal:host-gateway` when running in Docker
|
||||
|
||||
## `404 Resource not found`
|
||||
---
|
||||
### `404 Resource not found`
|
||||
|
||||
### Symptoms
|
||||
**Symptoms**
|
||||
|
||||
```python
|
||||
Traceback (most recent call last):
|
||||
@ -123,12 +134,12 @@ Traceback (most recent call last):
|
||||
openai.NotFoundError: Error code: 404 - {'error': {'code': '404', 'message': 'Resource not found'}}
|
||||
```
|
||||
|
||||
### Details
|
||||
**Details**
|
||||
|
||||
This happens when LiteLLM (our library for connecting to different LLM providers) can't find
|
||||
the API endpoint you're trying to connect to. Most often this happens for Azure or ollama users.
|
||||
|
||||
### Workarounds
|
||||
**Workarounds**
|
||||
|
||||
* Check that you've set `LLM_BASE_URL` properly
|
||||
* Check that model is set properly, based on the [LiteLLM docs](https://docs.litellm.ai/docs/providers)
|
||||
@ -142,9 +153,10 @@ the API endpoint you're trying to connect to. Most often this happens for Azure
|
||||
* See if you can connect to the LLM using `curl`
|
||||
* Try [connecting via LiteLLM directly](https://github.com/BerriAI/litellm) to test your setup
|
||||
|
||||
## `make build` getting stuck on package installations
|
||||
---
|
||||
### `make build` getting stuck on package installations
|
||||
|
||||
### Symptoms
|
||||
**Symptoms**
|
||||
|
||||
Package installation stuck on `Pending...` without any error message:
|
||||
|
||||
@ -158,17 +170,14 @@ Package operations: 286 installs, 0 updates, 0 removals
|
||||
- Installing typing-extensions (4.11.0): Pending...
|
||||
```
|
||||
|
||||
### Details
|
||||
**Details**
|
||||
|
||||
In rare cases, `make build` can seemingly get stuck on package installations
|
||||
without any error message.
|
||||
|
||||
### Workarounds
|
||||
**Workarounds**
|
||||
|
||||
* The package installer Poetry may miss a configuration setting for
|
||||
where credentials are to be looked up (keyring).
|
||||
|
||||
### Workaround
|
||||
The package installer Poetry may miss a configuration setting for where credentials are to be looked up (keyring).
|
||||
|
||||
First check with `env` if a value for `PYTHON_KEYRING_BACKEND` exists.
|
||||
If not, run the below command to set it to a known value and retry the build:
|
||||
@ -177,20 +186,21 @@ If not, run the below command to set it to a known value and retry the build:
|
||||
export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring
|
||||
```
|
||||
|
||||
## Sessions are not restored
|
||||
---
|
||||
### Sessions are not restored
|
||||
|
||||
### Symptoms
|
||||
**Symptoms**
|
||||
|
||||
OpenDevin usually asks whether to resume or start a new session when opening the UI.
|
||||
But clicking "Resume" still starts a fresh new chat.
|
||||
|
||||
### Details
|
||||
**Details**
|
||||
|
||||
With a standard installation as of today session data is stored in memory.
|
||||
Currently, if OpenDevin's service is restarted, previous sessions become
|
||||
invalid (a new secret is generated) and thus not recoverable.
|
||||
|
||||
### Workarounds
|
||||
**Workarounds**
|
||||
|
||||
* Change configuration to make sessions persistent by editing the `config.toml`
|
||||
file (in OpenDevin's root folder) by specifying a `file_store` and an
|
||||
|
||||
@ -5,11 +5,6 @@ Please be sure to run all commands inside your WSL terminal.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: 'docker' could not be found in this WSL 2 distro.
|
||||
|
||||
If you are using Docker Desktop, make sure to start it before calling any docker command from inside WSL.
|
||||
Docker also needs to have the WSL integration option activated.
|
||||
|
||||
### Recommendation: Do not run as root user
|
||||
|
||||
For security reasons, it is highly recommended to not run OpenDevin as the root user, but a user with a non-zero UID.
|
||||
@ -21,6 +16,13 @@ References:
|
||||
* [Set default user in WSL](https://www.tenforums.com/tutorials/128152-set-default-user-windows-subsystem-linux-distro-windows-10-a.html#option2)
|
||||
Hint about the 2nd reference: for Ubuntu users, the command could actually be "ubuntupreview" instead of "ubuntu".
|
||||
|
||||
---
|
||||
### Error: 'docker' could not be found in this WSL 2 distro.
|
||||
|
||||
If you are using Docker Desktop, make sure to start it before calling any docker command from inside WSL.
|
||||
Docker also needs to have the WSL integration option activated.
|
||||
|
||||
---
|
||||
### Failed to create opendevin user
|
||||
|
||||
If you encounter the following error during setup:
|
||||
@ -35,6 +37,7 @@ You can resolve it by running:
|
||||
export SANDBOX_USER_ID=1000
|
||||
```
|
||||
|
||||
---
|
||||
### Poetry Installation
|
||||
|
||||
* If you face issues running Poetry even after installing it during the build process, you may need to add its binary path to your environment:
|
||||
@ -57,6 +60,7 @@ rm -r ~/.cache/pypoetry
|
||||
make build
|
||||
```
|
||||
|
||||
---
|
||||
### NoneType object has no attribute 'request'
|
||||
|
||||
If you are experiencing issues related to networking, such as `NoneType object has no attribute 'request'` when executing `make run`, you may need to configure your WSL2 networking settings. Follow these steps:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user