OpenHands: The AI Agent That Writes Code and Executes Commands

OpenHands is an AI-powered software development agent designed to function much like a human peer. It can modify code, execute terminal commands, browse the web, and call APIs. It is even capable of sourcing snippets from Stack Overflow when a specific implementation requires external documentation.

The platform provides a comprehensive suite of integrated tools, including a chat interface, a code editor, a web browser, and a Jupyter IPython console. Coding tasks are managed by the OpenDevin CodeAct 1.0 model, which serves as the system's core. This model is capable of handling complex logic—from writing scripts that aggregate GitHub commit counts to implementing HTTP retry logic or generating data visualizations with matplotlib.

Running OpenHands with Docker

The most straightforward way to get started is via Docker. First, pull the required runtime image:

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.28-nikolaik

Then, launch the container using the following command:

docker run -it --rm --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.28-nikolaik \
    -e LOG_ALL_EVENTS=true \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands-state:/.openhands-state \
    -p 3000:3000 \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app \
    docker.all-hands.dev/all-hands-ai/openhands:0.28

Once the container is running, navigate to http://localhost:3000 in your web browser.

You will need to configure a model provider and an API key. While several models are supported, Anthropic's Claude 3.5 Sonnet (anthropic/claude-3-5-sonnet-20241022) is currently the top performer for these tasks.

Alternative Usage Methods

OpenHands offers several flexible deployment options, such as mounting your local filesystem, running in headless mode for automated scripting, or interacting via a CLI. You can also integrate it into GitHub Actions to trigger based on specific issue labels. For detailed instructions, refer to the "Running OpenHands" section in the official documentation.

OpenHands is currently optimized for use on an individual developer's local workstation. It does not yet include built-in multi-tenant isolation or enterprise-level scaling. For shared or high-scale deployments, contact the team regarding advanced options.

If you wish to modify the source code, consult Development.md. If you encounter issues during setup or execution, the troubleshooting guide provides solutions for common problems.

Core Capabilities

Starting from a Clean Slate

You can initiate a task with a simple, direct instruction:

"Write a bash script hello.sh that prints 'hello world!'"

OpenHands will write the script, update the file permissions, and execute it to verify the output.

You can then iterate on the result:

"Modify hello.sh to accept a name as the first argument. Default to 'world' if no argument is provided."

Or even switch to a different language:

"Convert hello.sh to a Ruby script and execute it."

Note that the agent may require a brief moment to configure the necessary environment for new languages.

Greenfield Development

The agent is particularly effective at "greenfield" tasks where no prior code context exists. For the best results, be specific about your requirements and preferred technology stack.

"Build a frontend-only TODO app in React. Store all task state in localStorage."

Once the base application is functional, you can refine the features:

"Add an optional due date field for each task."

It is good practice to commit and push changes frequently. You can direct the agent to handle this as well:

"Commit these changes and push them to a new branch titled 'feature/due-dates'."

Integrating Code into Existing Projects

OpenHands excels at inserting new features into established codebases. For example, you can ask it to add a linting workflow to your repository; it will inspect the project to identify the programming language and create a corresponding .github/workflows/lint.yml file.

"Add a GitHub Action to lint the code in this repository."

While the agent can navigate the repository using ls and grep, providing specific file paths helps save time and reduce token usage.

"Modify ./backend/api/routes.js to add a new route that returns the complete list of tasks."

"Create a new React component in ./frontend/components to display a list of widgets, utilizing the existing Widget component."

Code Refactoring

OpenHands is well-suited for targeted refactoring tasks, such as breaking down long functions or renaming variables. However, it is usually better to avoid asking for a total rewrite of a large codebase in a single step.

"Rename all single-letter variables in ./app.go to more descriptive names."

"Split the build_and_deploy_widgets function in widget.php into two distinct functions: build_widgets and deploy_widgets."

"Deconstruct ./api/routes.js into separate files organized by route."

Bug Resolution

The agent can identify and fix software defects, though bug resolution often requires more detailed context. If you have already identified the root cause, OpenHands can implement the fix directly.

"The /subscribe endpoint is currently rejecting .io domains. Please fix this validation logic."

"The search_widgets function in ./app.py is case-sensitive. Modify it to be case-insensitive."

Using a test-driven approach often yields the best results. You can ask the agent to write a failing test case before implementing the fix.

"The hello function crashes when passed an empty string. Write a test that reproduces this crash, then fix the code so the test passes."

Tips for Optimal Results

While OpenHands can assist with almost any programming task, a few best practices will help you get the most out of the agent:

• Incremental Steps: Break large tasks into smaller, manageable milestones.
• Specific Instructions: Provide clear, unambiguous prompts.
• Contextual Clarity: Ensure the agent has access to the relevant files and background information.
• Frequent Version Control: Commit and push your code regularly to maintain a clean history.

For further optimization, refer to the prompt best practices guide.