diff --git a/README.md b/README.md index 2c165041cd..71df2601af 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Join our Discord community Credits
- Check out the documentation + Check out the documentation Paper on Arxiv Evaluation Benchmark Score
@@ -54,8 +54,12 @@ docker run -it --pull=always \ ghcr.io/all-hands-ai/openhands:0.9 ``` -You'll find OpenHands running at [http://localhost:3000](http://localhost:3000). -Visit [Getting Started](https://docs.all-hands.dev/modules/usage/getting-started) for more information and setup. +You'll find OpenHands running at [http://localhost:3000](http://localhost:3000)! + +You can also run OpenHands in a scriptable [headless mode](https://docs.all-hands.dev/modules/usage/how-to/headless-mode), +or as an [interactive CLI](https://docs.all-hands.dev/modules/usage/how-to/cli-mode). + +Visit [Getting Started](https://docs.all-hands.dev/modules/usage/getting-started) for more information and setup instructions. If you want to modify the OpenHands source code, check out [Development.md](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md). @@ -64,7 +68,7 @@ Having issues? The [Troubleshooting Guide](https://docs.all-hands.dev/modules/us ## 📖 Documentation To learn more about the project, and for tips on using OpenHands, -**check out our [documentation](https://docs.all-hands.dev/modules/usage/intro)**. +**check out our [documentation](https://docs.all-hands.dev/modules/usage/getting-started)**. There you'll find resources on how to use different LLM providers (like ollama and Anthropic's Claude), troubleshooting resources, and advanced configuration options. diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 2f81477729..17ca650247 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -4,8 +4,8 @@ import { themes as prismThemes } from "prism-react-renderer"; const config: Config = { title: "OpenHands", - tagline: "An Open Platform for AI Software Developers as Generalist Agents", - favicon: "img/logo.png", + tagline: "Code Less, Make More", + favicon: "img/logo-square.png", // Set the production url of your site here url: "https://docs.all-hands.dev", @@ -73,23 +73,28 @@ const config: Config = { type: "docSidebar", sidebarId: "docsSidebar", position: "left", - label: "Docs", + label: "User Guides", }, { type: "docSidebar", sidebarId: "apiSidebar", position: "left", - label: "Codebase", + label: "Python API", + }, + { + type: 'localeDropdown', + position: 'left', + }, + { + href: "https://all-hands.dev", + label: "Company", + position: "right", }, { href: "https://github.com/All-Hands-AI/OpenHands", label: "GitHub", position: "right", }, - { - type: 'localeDropdown', - position: 'left', - }, ], }, prism: { diff --git a/docs/modules/usage/getting-started.md b/docs/modules/usage/getting-started.md index 82b3242990..a5596dba7c 100644 --- a/docs/modules/usage/getting-started.md +++ b/docs/modules/usage/getting-started.md @@ -28,6 +28,9 @@ docker run -it --pull=always \ ghcr.io/all-hands-ai/openhands:0.9 ``` +You can also run OpenHands in a scriptable [headless mode](https://docs.all-hands.dev/modules/usage/how-to/headless-mode), +or as an [interactive CLI](https://docs.all-hands.dev/modules/usage/how-to/cli-mode). + ## Setup After running the command above, you'll find OpenHands running at [http://localhost:3000](http://localhost:3000). diff --git a/docs/modules/usage/how-to/cli-mode.md b/docs/modules/usage/how-to/cli-mode.md index 88f00794f2..946ba26516 100644 --- a/docs/modules/usage/how-to/cli-mode.md +++ b/docs/modules/usage/how-to/cli-mode.md @@ -1,8 +1,10 @@ -# Running in CLI Mode +# CLI Mode -OpenHands can be run in an interactive CLI mode, which allows users to start an interactive session via the command line. This mode is different from the headless mode, which is non-interactive. +OpenHands can be run in an interactive CLI mode, which allows users to start an interactive session via the command line. -## Starting an Interactive Session +This mode is different from the [headless mode](headless-mode), which is non-interactive and better for scripting. + +## With Python To start an interactive OpenHands session via the command line, follow these steps: @@ -16,7 +18,11 @@ poetry run python -m openhands.core.cli This command will start an interactive session where you can input tasks and receive responses from OpenHands. -## Running in CLI Mode with Docker +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 To run OpenHands in CLI mode with Docker, follow these steps: @@ -26,18 +32,18 @@ To run OpenHands in CLI mode with Docker, follow these steps: WORKSPACE_BASE=$(pwd)/workspace ``` -2. Set `LLM_API_KEY` to an API key, e.g., for OpenAI or Anthropic: +2. Set `LLM_MODEL` to the model you want to use: + +```bash +LLM_MODEL="claude-3-5-sonnet-20240620" +``` + +3. Set `LLM_API_KEY` to an API key, e.g., for OpenAI or Anthropic: ```bash LLM_API_KEY="abcde" ``` -3. Set `LLM_MODEL` to the model you want to use: - -```bash -LLM_MODEL="gpt-4o" -``` - 4. Run the following Docker command: ```bash @@ -57,11 +63,6 @@ docker run -it \ This command will start an interactive session in Docker where you can input tasks and receive responses from OpenHands. -## Difference Between CLI Mode and Headless Mode - -- **CLI Mode**: Interactive mode where users can input tasks and receive responses in real-time. It is suitable for users who prefer or require a command-line interface. -- **Headless Mode**: Non-interactive mode where tasks are executed without user interaction. It is suitable for automation and scripting purposes. - ## Examples of CLI Commands and Expected Outputs Here are some examples of CLI commands and their expected outputs: diff --git a/docs/modules/usage/how-to/custom-sandbox-guide.md b/docs/modules/usage/how-to/custom-sandbox-guide.md index 7367499745..ff1bb857fe 100644 --- a/docs/modules/usage/how-to/custom-sandbox-guide.md +++ b/docs/modules/usage/how-to/custom-sandbox-guide.md @@ -1,7 +1,11 @@ -# Create and Use a Custom Docker Sandbox +# Custom Sandbox -The default OpenHands sandbox comes with a [minimal ubuntu configuration](https://github.com/All-Hands-AI/OpenHands/blob/main/containers/sandbox/Dockerfile). -Your use case may need additional software installed by default. +The sandbox is where the agent does its work--instead of running commands directly on your computer +(which could be dangerous), the agent runs them inside of a Docker container. + +The default OpenHands sandbox comes with a +[minimal ubuntu configuration](https://github.com/All-Hands-AI/OpenHands/blob/main/containers/sandbox/Dockerfile). +Your use case may need additional software installed by default. In this case, you can build a custom sandbox image. There are two ways you can do so: diff --git a/docs/modules/usage/how-to/evaluation-harness.md b/docs/modules/usage/how-to/evaluation-harness.md index 903d079728..cb9b64754e 100644 --- a/docs/modules/usage/how-to/evaluation-harness.md +++ b/docs/modules/usage/how-to/evaluation-harness.md @@ -1,4 +1,4 @@ -# Contribute to OpenHands Evaluation Harness +# Evaluation This guide provides an overview of how to integrate your own evaluation benchmark into the OpenHands framework. @@ -12,7 +12,7 @@ Here's an example configuration file you can use to define and use multiple LLMs ```toml [llm] # IMPORTANT: add your API key here, and set the model to the one you want to evaluate -model = "gpt-4o-2024-05-13" +model = "claude-3-5-sonnet-20240620" api_key = "sk-XXX" [llm.eval_gpt4_1106_preview_llm] diff --git a/docs/modules/usage/how-to/headless-mode.md b/docs/modules/usage/how-to/headless-mode.md index fe07b6558e..46b557b173 100644 --- a/docs/modules/usage/how-to/headless-mode.md +++ b/docs/modules/usage/how-to/headless-mode.md @@ -1,15 +1,9 @@ -# Running in Headless Mode +# Headless Mode -You can run OpenHands via a CLI, without starting the web application. This makes it easy to automate tasks with OpenHands. +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. -## Difference Between CLI Mode and Headless Mode - -- **CLI Mode**: Interactive mode where users can input tasks and receive responses in real-time. It is suitable for users who prefer or require a command-line interface. -- **Headless Mode**: Non-interactive mode where tasks are executed without user interaction. It is suitable for automation and scripting purposes. - -For more information on CLI mode, refer to the [CLI Mode documentation](./cli-mode.md). - -As with other modes, the environment is configurable via environment variables or by saving values into [config.toml](https://github.com/All-Hands-AI/OpenHands/blob/main/config.template.toml) +This is different from [CLI Mode](cli-mode), which is interactive, and better for active development. ## With Python @@ -17,8 +11,46 @@ To run OpenHands in headless mode with Python, [follow the Development setup instructions](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md), and then run: -### Headless with Python - ```bash 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 + +1. Set `WORKSPACE_BASE` to the directory you want OpenHands to edit: + +```bash +WORKSPACE_BASE=$(pwd)/workspace +``` + +2. Set `LLM_MODEL` to the model you want to use: + +```bash +LLM_MODEL="claude-3-5-sonnet-20240620" +``` + +3. Set `LLM_API_KEY` to an API key, e.g., for OpenAI or Anthropic: + +```bash +LLM_API_KEY="abcde" +``` + +4. Run the following Docker command: + +```bash +docker run -it \ + --pull=always \ + -e SANDBOX_USER_ID=$(id -u) \ + -e WORKSPACE_MOUNT_PATH=$WORKSPACE_BASE \ + -e LLM_API_KEY=$LLM_API_KEY \ + -e LLM_MODEL=$LLM_MODEL \ + -v $WORKSPACE_BASE:/opt/workspace_base \ + -v /var/run/docker.sock:/var/run/docker.sock \ + --add-host host.docker.internal:host-gateway \ + --name openhands-app-$(date +%Y%m%d%H%M%S) \ + ghcr.io/all-hands-ai/openhands:0.9 \ + poetry run python -m openhands.core.main -t "write a bash script that prints hi" +``` diff --git a/docs/modules/usage/how-to/how-to.md b/docs/modules/usage/how-to/how-to.md deleted file mode 100644 index bff43fc3e2..0000000000 --- a/docs/modules/usage/how-to/how-to.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sidebar_position: 6 ---- - -# 🔎 How To Section diff --git a/docs/modules/usage/how-to/openshift-example.md b/docs/modules/usage/how-to/openshift-example.md index e33e59eaa5..1f259aaaa0 100644 --- a/docs/modules/usage/how-to/openshift-example.md +++ b/docs/modules/usage/how-to/openshift-example.md @@ -1,6 +1,6 @@ -# Use OpenHands in OpenShift/K8S +# Kubernetes -There are different ways this can be accomplished. This guide goes through one possible way: +There are different ways you might run OpenHands on Kubernetes or OpenShift. This guide goes through one possible way: 1. Create a PV "as a cluster admin" to map workspace_base data and docker directory to the pod through the worker node 2. Create a PVC to be able to mount those PVs to the pod 3. Create a pod which contains two containers; the OpenHands and Sandbox containers diff --git a/docs/modules/usage/intro.mdx b/docs/modules/usage/intro.mdx deleted file mode 100644 index 307473e187..0000000000 --- a/docs/modules/usage/intro.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -sidebar_position: 1 ---- - -# 💻 OpenHands - -OpenHands is an **autonomous AI software engineer** capable of executing complex engineering tasks and collaborating actively with users on software development projects. -This project is fully open-source, so you can use and modify it however you like. - -:::tip -Explore the codebase of OpenHands on [GitHub](https://github.com/All-Hands-AI/OpenHands) or join one of our communities! - - - Contributors - - - Forks - - - Stargazers - - - Issues - -

- - MIT License - -

- - Join our Slack community - - - Join our Discord community - -::: - -## 🛠️ Getting Started - -[Check out the getting started guide on Github](https://github.com/All-Hands-AI/OpenHands?tab=readme-ov-file#-getting-started) - -[contributors-shield]: https://img.shields.io/github/contributors/All-Hands-AI/OpenHands?style=for-the-badge -[contributors-url]: https://github.com/All-Hands-AI/OpenHands/graphs/contributors -[forks-shield]: https://img.shields.io/github/forks/All-Hands-AI/OpenHands?style=for-the-badge -[forks-url]: https://github.com/All-Hands-AI/OpenHands/network/members -[stars-shield]: https://img.shields.io/github/stars/All-Hands-AI/OpenHands?style=for-the-badge -[stars-url]: https://github.com/All-Hands-AI/OpenHands/stargazers -[issues-shield]: https://img.shields.io/github/issues/All-Hands-AI/OpenHands?style=for-the-badge -[issues-url]: https://github.com/All-Hands-AI/OpenHands/issues -[license-shield]: https://img.shields.io/github/license/All-Hands-AI/OpenHands?style=for-the-badge -[license-url]: https://github.com/All-Hands-AI/OpenHands/blob/main/LICENSE diff --git a/docs/modules/usage/llms/local-llms.md b/docs/modules/usage/llms/local-llms.md index a43008c530..df1bce939e 100644 --- a/docs/modules/usage/llms/local-llms.md +++ b/docs/modules/usage/llms/local-llms.md @@ -32,7 +32,7 @@ starcoder2:latest f67ae0f64584 1.7 GB 19 hours ago ### Docker -Use the instructions [here](../intro) to start OpenHands using Docker. +Use the instructions [here](../getting-started) to start OpenHands using Docker. But when running `docker run`, you'll need to add a few more arguments: ```bash diff --git a/docs/sidebars.ts b/docs/sidebars.ts index ed1b823008..5c02ccc3ad 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -1,8 +1,51 @@ import type { SidebarsConfig } from "@docusaurus/plugin-content-docs"; const sidebars: SidebarsConfig = { - docsSidebar: [{ type: "autogenerated", dirName: "usage" }], apiSidebar: [require("./modules/python/sidebar.json")], + docsSidebar: [{ + type: 'doc', + label: 'Getting Started', + id: 'usage/getting-started', + }, { + type: 'doc', + label: 'Troubleshooting', + id: 'usage/troubleshooting/troubleshooting', + }, { + type: 'doc', + label: 'Feedback', + id: 'usage/feedback', + }, { + type: 'category', + label: 'How-to Guides', + items: [{ + type: 'doc', + id: 'usage/how-to/cli-mode', + }, { + type: 'doc', + id: 'usage/how-to/headless-mode', + }, { + type: 'doc', + id: 'usage/how-to/custom-sandbox-guide', + }, { + type: 'doc', + id: 'usage/how-to/evaluation-harness', + }, { + type: 'doc', + id: 'usage/how-to/openshift-example', + }] + }, { + type: 'doc', + label: 'LLMs', + id: 'usage/llms/llms', + }, { + type: 'doc', + label: 'Architecture', + id: 'usage/architecture/architecture', + }, { + type: 'doc', + label: 'About', + id: 'usage/about', + }], }; export default sidebars; diff --git a/docs/src/components/CustomFooter.tsx b/docs/src/components/CustomFooter.tsx index 0a5eddad99..b461d4dd17 100644 --- a/docs/src/components/CustomFooter.tsx +++ b/docs/src/components/CustomFooter.tsx @@ -7,17 +7,6 @@ function CustomFooter() { return (