Getting Started with OpenHands and a Local LLM

Overview

OpenHands is an AI software agent that can write code, run commands, browse the web, and edit files in a real workspace. Instead of copying suggestions out of a chat window, you point the agent at a project folder and let it do the work: implement a feature, fix a bug, write tests, or explain a codebase.

Agent Canvas is the recommended browser UI for running OpenHands. A single agent-canvas command starts the agent server, the automation backend, and the web frontend together, so you can drive a conversation with the agent from your browser.

To keep everything on your AMD system, the agent talks to a local model served by Lemonade Server. Lemonade exposes that model through an OpenAI-compatible API, so Agent Canvas can configure it like any other OpenAI-style endpoint while the model, your code, and the conversation context all stay on your machine.

In this playbook, you will start a local model, launch Agent Canvas, point it at that model, and run your first coding task against a real project folder.

What You’ll Learn

• How to start Lemonade Server and confirm a local model answers chat requests
• How to install and launch Agent Canvas from the npm package
• How to configure Agent Canvas to use a local Lemonade model as the LLM
• How to start an OpenHands conversation and watch the agent edit files and run commands in a workspace
• How to review what the agent changed and steer it with follow-up messages

Core Concepts

Setting the Memory Configuration

sudo apt install pipx
pipx ensurepath

pipx install amd-debug-tools

amd-ttm

amd-ttm --set <NUM>

Prerequisites

msiexec /i lemonade-server-minimal.msi /qn

sudo add-apt-repository ppa:lemonade-team/stable
sudo apt install lemonade-server

yay -S lemonade-server

lemonade --version

lemonade version x.y.z

node --version
npm --version

curl -o- https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh | bash

# Download and install Node.js:
brew install node@22

# Verify the Node.js version:
node -v # Should print "v22.22.1".

# Verify npm version:
npm -v # Should print "10.9.4".

msiexec /i lemonade-server-minimal.msi /qn

sudo add-apt-repository ppa:lemonade-team/stable
sudo apt install lemonade-server

yay -S lemonade-server

lemonade --version

lemonade version x.y.z

You need:

• Lemonade Server installed and able to serve the model below.

• A project folder to work in. This can be any local git repository or code directory you want the agent to work on.

1. Start Lemonade Server

Start the model from the Lemonade CLI:

lemonade config set llamacpp.backend=vulkan
lemonade config set ctx_size=65536
lemonade run "Qwen3.6-35B-A3B-GGUF"

Choose a model that fits your hardware. Qwen3.6-35B-A3B-GGUF (~20 GB) is a strong coding model but needs a large memory pool. If your device has limited memory or GPU VRAM, pick a smaller GGUF model from the Lemonade model library instead and use that model ID throughout this playbook.

Lemonade exposes an OpenAI-compatible API at:

http://127.0.0.1:13305/api/v1

2. Verify the Local Model

Confirm Lemonade can serve the selected model:

curl -s "http://127.0.0.1:13305/api/v1/models" | python3 -m json.tool

Then send a small chat request:

curl -sS "http://127.0.0.1:13305/api/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen3.6-35B-A3B-GGUF",
    "messages": [
      {"role": "user", "content": "Reply with exactly: OK"}
    ],
    "temperature": 0,
    "max_tokens": 64
  }' | python3 -m json.tool

If this returns a choices array, Lemonade is ready for Agent Canvas.

3. Install and Launch Agent Canvas

npm install -g @openhands/agent-canvas

agent-canvas

agent-canvas --port 3000

$env:PROJECTS_PATH = Join-Path $HOME "projects"
New-Item -ItemType Directory -Force -Path $env:PROJECTS_PATH, (Join-Path $env:USERPROFILE ".openhands") | Out-Null

docker pull ghcr.io/openhands/agent-canvas:1.14.0

docker run -it --rm `
  -p 8000:8000 `
  -v "$($env:USERPROFILE)\.openhands:/home/openhands/.openhands" `
  -v "$($env:PROJECTS_PATH):/projects" `
  ghcr.io/openhands/agent-canvas:1.14.0

4. Configure the Local LLM

On first launch, Agent Canvas opens an onboarding flow. In that flow:

1. Keep OpenHands selected as the agent and click Next.
2. On Set up your LLM, select Advanced.
3. Keep Authentication set to API key.
4. Set Custom Model to openai/Qwen3.6-35B-A3B-GGUF.
5. Set Base URL to http://127.0.0.1:13305/api/v1.

   On Windows the stack runs in a container, which cannot reach the host at 127.0.0.1. Use http://host.docker.internal:13305/api/v1 instead so the containerized agent can reach Lemonade running on the Windows host.

6. For API Key, enter any non-empty placeholder such as lemonade-local. Lemonade does not require a real key, but the OpenHands client needs a value to send.
7. Click Next.

The completed Advanced settings should look like this. The API key field is masked by the UI.

Agent Canvas saves these values as an LLM profile. If your version asks you to name that profile, use a no-space name such as lemonade-local. If you change models later, open Settings > LLM and update the same Advanced fields. You can switch saved profiles from the chat input with the /model command.

5. Open a Workspace

The agent can only read and modify files inside a workspace you choose. Before starting a task, point Agent Canvas at your project folder:

1. From the home screen, choose Open Workspace.
2. Select the folder that contains your project (for example, a git repository you want the agent to work on).
3. Start a new conversation in that workspace.

Everything the agent does—reading files, running commands, editing code—is scoped to that workspace.

6. Run Your First Coding Task

With the workspace open and the local LLM selected, type a concrete task into the chat. A good first task is small and verifiable, for example:

Create a new file called hello.py that defines a function greet(name) that
returns "Hello, {name}!", and add a small test that prints greet("World")
when run as a script.

Watch the conversation timeline. OpenHands will:

• Read the workspace to understand the layout.
• Create hello.py with the requested function and test block.
• Optionally run python3 hello.py to verify the output.
• Report what it did and any command output in the chat.

You should see the new file appear in the workspace, and the agent’s final message should describe the change it made. This is the payoff moment: the agent wrote and ran real code in your project folder.

7. Review and Steer the Agent

After the agent finishes a step, review its work before accepting the next one:

• File changes: use the workspace file browser or the agent’s diff view to see exactly what was added, changed, or deleted.
• Command output: expand any command the agent ran to see stdout, stderr, and the exit code.
• Follow-ups: if the result is not what you wanted, reply in the same conversation with a correction. The agent keeps the prior context and iterates on the same files.

For example, if the test did not print the expected greeting, reply:

The script did not print anything. Run python3 hello.py and fix it so the
greet("World") test prints to stdout.

The agent will re-read the file, run the command, diagnose the issue, and edit the file again—all in the same conversation.

Troubleshooting

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.profile
. ~/.profile
npm install -g @openhands/agent-canvas

• The UI loads but the backend shows unhealthy: wait a minute or two for the agent server to finish starting, then refresh. If it stays unhealthy, restart the stack and check the logs for errors.
• Lemonade chat requests fail with a connection error: confirm curl -fsS "http://127.0.0.1:13305/api/v1/health" succeeds and that Lemonade is still serving the model with lemonade status.
• The agent errors with a context-length or token-limit message: start a fresh conversation so the agent does not carry an oversized history. If it keeps happening, restart Lemonade with a larger ctx_size than the default 65536 (for example ctx_size=131072), memory permitting.
• The agent produces low-quality or incomplete edits: switch to a larger model in Lemonade, or give the agent a smaller, more concrete task and let it finish before asking for the next change.

Next Steps

• Try a larger task in the same workspace, such as adding a unit test file or fixing a known bug, and review the agent’s diff before keeping the change.
• Connect an MCP server such as GitHub or Slack under Customize so the agent can read issues or post updates while it works.
• Save several LLM profiles (a fast small model and a stronger large model) and switch between them with /model mid-conversation.
• Move on to OpenHands automations to turn recurring development loops into scheduled or event-triggered agent runs.

Resources

• OpenHands documentation
• Agent Canvas overview
• Agent Canvas setup
• LLM profiles and model configuration
• Lemonade Server documentation