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. Note: This large context size is currently supported only by the llamacpp backend.

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. The only thing that we suggest is that when using models that are able to use tools, such as Qwen3-Coder-30B-A3B-Instruct-GGUF, that native tool use is enabled. This can be done by launching OpenHands via docker and adding -e LLM_NATIVE_TOOL_CALLING=true to the docker run... command in the OpenHands documentation.

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. Click on see advanced settings as shown in the image below: configuration

  1. Once in the Settings menu, toggle the Advanced switch to see all configuration options.

  2. Set the following values in the configuration:

  3. Custom Model: openai/Qwen3-Coder-30B-A3B-Instruct-GGUF

  4. Base URL: http://host.docker.internal:8000/api/v1/
  5. API Key: Use a dash or any character.

The setup should look as follows::

advanced-configuration

  1. Click Save Settings.

Using OpenHands

  1. To launch a new project, click Launch from Scratch. If you do not see this screen, click the + on the top left. intro-screen

  2. Wait for the status on the bottom right to say Awaiting user input. and enter your prompt into the text box. For example: "Write me a flask website that prints "Welcome to OpenHands + Lemonade!" make the website fun with a theme of lemons and laptops." as shown below: initial-prompt-lemonade-website

  3. 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:

lemonade-website-in-progress

  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. In the Terminal at the bottom, we can see that the software agent has launched the web server hosting the newly developed website at port number 52877.

finished-prompt-lemonade-website

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

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

  • Certain small models can struggle with tool calling. This can be seen by the agent continously running the same command that is resulting in an error. For example, we have found that it is common for certain models to initially struggle with the tool required to create files. In our experience after multiple attempts, the model is able to figure out that it is not using the tool correctly and tries another method to use the tool. An example of this can be seen below. If this issue persists we recommend enabling native tool in OpenHands. This can be done by launching OpenHands via docker and adding -e LLM_NATIVE_TOOL_CALLING=true to the docker run... command in the OpenHands documentation. tool-calling-struggles

  • 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/

  • We have run into some issues where despite the source code for a requested website being generated correctly, it cannot be accessed through the browser. When this happens, you can still copy the generated source into your own environment and run the provided commands to serve the generated website.

Resources