Skip to content

OpenHands

OpenHands is an open-source AI coding agent. This document explains how to configure OpenHands to target local AI models using Lemonade Server, enabling code generation, editing, and chat capabilities. Much of this guide uses the fantastic guide from OpenHands on running local models, with added details on integrating with Lemonade Server.

There are a few things to note on this integration:

  • This integration is in its early stages. We encourage you to test it and share any issues you encounter—your feedback will help us make the Lemonade–OpenHands functionality as robust as possible.

  • Due to the complexity of the scaffolding of agentic software agents, the compute requirements for this application is very high. For a low latency experience, we recommend using a discrete GPU with at least 16 GB of VRAM, or a Strix Halo PC with at least 64 GB of RAM.

Prerequisites

  • Docker: OpenHands leverages Docker containers to create environments for the software agents. To see how to install docker for OpenHands, see their documentation.
  • Lemonade Server: Install Lemonade Server using the Getting Started Guide.
  • Server running: Ensure Lemonade Server is running on http://localhost:8000
  • Models installed: Ensure at least one model from the supported models list is downloaded locally. For OpenHands functionality, we recommend models denoted with the coding label, which can be found in your Lemonade installation's Model Manager or in the labels of the models list.

Installation

Launch Lemonade Server with the correct settings

Since OpenHands runs inside Docker containers, the containers must be able to access the Lemonade Server. The simplest way to enable this is by running the Lemonade Server on IP address 0.0.0.0, which is accessible from within Docker. Additionally, OpenHands recommends using a context length of at least 32,768 tokens. To configure Lemonade with a non-default context size, include the --ctx-size parameter set to 32768.

lemonade-server serve --host 0.0.0.0 --ctx-size 32768

Installing OpenHands

Follow the OpenHands documentation on how to install OpenHands locally. This can be done via the uvx tool or through docker. No special installation instructions are necessary to integrate with Lemonade.

In the next section, we will show how to configure OpenHands to talk to a local model running via Lemonade Server.

Launching OpenHands

To launch OpenHands, open a browser and navigate to http://localhost:3000. When first launching the application, the "AI Provider Configuration" window will appear. Select "Lemonade" as the LLM Provider and your favorite coding model from the drop-down. For a nice balance of quality and speed, we recommend Qwen3-Coder-30B-A3B-Instruct-GGUF. When complete, hit Save Changes.

openhands-llm-settings-wide

Using OpenHands

  1. To launch a new conversation, click New Conversation. If you do not see this screen, click the + on the top left.

open-hands-main-page

  1. Wait for the status on the bottom right to say Awaiting user input. and enter your prompt into the text box. For example: "Create a website that showcases Ryzen AI and the ability to run the OpenHands coding agents locally through the Lemonade software stack. Make the website fun with a theme of lemonade and laptops." as shown below:

prompt

  1. Hit Enter to start the process. This will bring you to a new screen that allows you to monitor the agent operating in its environment to develop the requested application. An example of the agent working on the requested application can be seen below:

mid-coding

  1. When complete, the user can interact with the environment and artifacts created by the software agent. An image of the workspace at the end of developing the application can be seen below. On the left, we can see that the coding agent has launched the web server hosting the newly developed website at port number 55519.

finished-code

  1. Use your browser to go to the web application developed by the software agent. Below is an image showing what was created:

website

  1. That's it! You just created a website from scratch using OpenHands integrated with a local LLM powered by Lemonade Server.

Suggestions on what to try next: Prompt OpenHands with Lemonade Server to develop some simple games that you can play via a web browser. For example, with the prompt "Write me a simple pong game that I can play on my browser. Make it so I can use the up and down arrows to control my side of the game. Make the game lemon and laptop themed." OpenHands with Lemonade Server was able to generate the following pong game, which included user-controls, a computer-controlled opponent, and scorekeeping:

pong-game-new

Common Issues

  • If on OpenHands you get an error with the message: The request failed with an internal server error and in the Lemonade log you see many WARNING: Invalid HTTP request received this is most likely because the base URL set in the settings is using https instead of http. If this occurs, update the base URL in the settings to http://host.docker.internal:8000/api/v1/

Resources