OpenHands for Unraid

A plug-and-play Unraid Community Applications template for OpenHands — the open-source AI software-development agent. Pre-wired for local Ollama with qwen2.5-coder:14b, Docker-socket sandboxing, and host.docker.internal routing. Install from the Unraid Apps tab, hit Apply, open the WebUI.

Table of Contents

1. What is this?
2. Features
3. Quick Start on Unraid
4. Configuration
5. GitHub Personal Access Token
6. Switching to OpenAI / Anthropic / other LLMs
7. Updating
8. Troubleshooting
9. Security Notes
10. Screenshots
11. Contributing / License
12. Support this project

1. What is this?

OpenHands (formerly OpenDevin) is an open-source autonomous agent that can read, write, run and debug code, browse the web, and execute shell commands in isolated sandbox containers.

This repository is not a fork of OpenHands. It only contains the Unraid Community Applications metadata — an XML template, an icon and this README — that tells Unraid how to deploy the upstream docker.openhands.dev/openhands/openhands image in a sensible default configuration for a typical Unraid box.

What this template gives you over a bare docker run:

• Pre-configured for Ollama — defaults point at ollama/qwen2.5-coder:14b via host.docker.internal, so a local Ollama install on the Unraid host works out of the box, no LLM gateway needed
• Sandbox-ready — the Unraid Docker socket is mounted, the right SANDBOX_VOLUMES and --add-host flags are pre-set, so OpenHands can actually spawn its execution containers
• Persistent config — /.openhands is mapped to /mnt/user/appdata/openhands, workspace files live in /mnt/user/ai-workspace
• Embedded local embeddings — LLM_EMBEDDING_MODEL=local avoids surprise API calls
• Pinned to a known-good tag — the template ships with the OpenHands image pinned to :1.7. New versions are surfaced as Renovate PRs so every bump is reviewed before users get it.

2. Features

• ✅ Pre-configured for Ollama with qwen2.5-coder:14b as the default coding model
• ✅ Talks to the host via host.docker.internal (the --add-host host.docker.internal:host-gateway flag is set automatically), so http://host.docker.internal:11434 reaches Ollama on the Unraid host without bridging gymnastics
• ✅ Binds the Unraid Docker socket (/var/run/docker.sock) so OpenHands can spin up its per-task sandbox containers
• ✅ Workspace and sandbox volumes are kept in sync via SANDBOX_VOLUMES, so files the agent writes show up under /mnt/user/ai-workspace on the host
• ✅ Persistent agent state in /mnt/user/appdata/openhands
• ✅ Single template, no extra plugins or scripts required
• ✅ MIT-licensed wrapper — fork and adapt freely

3. Quick Start on Unraid

This is a plug-and-play Community Applications template. No SSH, no config-file editing.

Step 1 — Install from Apps

In the Unraid Web UI:

1. Go to the Apps tab.
2. Search for OpenHands.
3. Click Install.

[!NOTE] If this template hasn't been accepted into the CA index yet, the search won't find it. In that case, jump to § Manual install below — a one-time curl puts the template into your user-templates folder, and it then shows up under User templates in the Add Container dialog.

Step 2 — (Optional) make sure Ollama is reachable

Defaults assume you have Ollama running on the Unraid host (or in another container reachable as host.docker.internal:11434) with the qwen2.5-coder:14b model pulled:

ollama pull qwen2.5-coder:14b

If you want a different model or a remote LLM, see § 6.

Step 3 — Apply the template

The CA install opens the template form with everything pre-filled. You can leave every field at its default. The two you may want to tweak:

• Workspace Directory — defaults to /mnt/user/ai-workspace. This is where the agent reads and writes project files. Point it at an existing project share if you prefer. (If you change this, also adjust the Sandbox Volumes variable to match.)
• LLM Model — defaults to ollama/qwen2.5-coder:14b. Change to any LiteLLM-style model string.

Hit Apply. First start pulls the image (~3 GB) and warms up the embedding model.

Step 4 — Open the WebUI

http://<unraid-ip>:3000/

On first launch, OpenHands will ask you to confirm the LLM settings and to provide a GitHub Personal Access Token if you want it to interact with GitHub repos — see § 5.

Manual install (pre-CA-listing)

Until this repo is accepted into the Community Applications index, you can still load the template by hand. Run this once on the Unraid console or via SSH:

mkdir -p /boot/config/plugins/dockerMan/templates-user && \
curl -fsSL -o /boot/config/plugins/dockerMan/templates-user/my-OpenHands.xml \
  https://raw.githubusercontent.com/junkerderprovinz/unraid-apps/main/openhands/openhands.xml

Then in the Unraid Web UI: Docker → Add Container → in the Template dropdown, pick OpenHands under User templates.

Plain Docker (no Unraid)

docker run -d \
  --name openhands \
  --restart unless-stopped \
  --add-host host.docker.internal:host-gateway \
  -p 3000:3000 \
  -v /mnt/user/appdata/openhands:/.openhands \
  -v /mnt/user/ai-workspace:/workspace \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e SANDBOX_VOLUMES=/mnt/user/ai-workspace:/workspace:rw \
  -e LLM_API_KEY=ollama \
  -e LLM_MODEL=ollama/qwen2.5-coder:14b \
  -e LLM_BASE_URL=http://host.docker.internal:11434 \
  -e LLM_EMBEDDING_MODEL=local \
  docker.openhands.dev/openhands/openhands:1.7

4. Configuration

Ports & Volumes

Extra runtime flags

The template applies:

--add-host host.docker.internal:host-gateway

This lets the container reach services running on the Unraid host (Ollama, your dev DB, etc.) via http://host.docker.internal:<port>.

Image tag

The template ships pinned to docker.openhands.dev/openhands/openhands:1.7. New OpenHands versions are picked up by Renovate, which opens a PR bumping the tag once a new release is available. After review and merge, Unraid CA polls the repo within ~2 hours and offers the update to users via the standard Update Available notification. Users who want to override the tag manually can do so in the Unraid template's Repository field (Advanced View).

5. GitHub Personal Access Token

OpenHands can clone repos, push commits, and open PRs on your behalf — but only if you give it a token. The template does not ship a token (it shouldn't — tokens are personal).

1. On GitHub: Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token.
   • Scopes: repo (mandatory), workflow (optional, for editing Actions), read:org (optional).
2. Open the OpenHands WebUI at http://<unraid-ip>:3000/.
3. Click the gear icon → Git → GitHub → paste the token → Save.

The token is stored inside /mnt/user/appdata/openhands and never leaves your box.

[!WARNING] Treat the token like a password. Anyone with it can push to your repos.

6. Switching to OpenAI / Anthropic / other LLMs

OpenHands uses LiteLLM, so the model string is all that needs to change. Examples:

Edit the Unraid template's LLM_MODEL and LLM_API_KEY fields, hit Apply, done.

For Ollama on a different host (e.g. a GPU box on your LAN), change the LLM Base URL field from the default http://host.docker.internal:11434 to http://<gpu-host>:11434. For a hosted provider (OpenAI, Anthropic, …) clear that field — those use their own endpoints.

7. Updating

On Unraid: Docker tab → click the container → Force Update. Your /.openhands data is untouched. If a new OpenHands version is released, this repo's Renovate workflow opens a PR bumping the <Repository> tag; once merged, a new tagged release ships and CA re-pulls the template.

[!TIP] Tag-pin to a specific minor (e.g. :1.7) — OpenHands ships often and the floating :latest tag has shipped breaking changes in the past.

8. Troubleshooting

Sandbox server not running: http://host.docker.internal:xxxxx

9. Security Notes

• Docker socket = root on the host. Mounting /var/run/docker.sock gives this container full control over your Unraid Docker daemon. Treat the OpenHands WebUI like a root shell — don't expose port 3000 to the internet without auth in front of it. A reverse proxy with authentication (e.g. NPM + Authelia / Authentik) is the right pattern.
• The agent runs code. That's the whole point. Sandbox containers reduce the blast radius but don't eliminate it — keep /mnt/user/ai-workspace on a share that doesn't contain anything you'd cry about losing.
• Your LLM sees your code. If you use a hosted LLM (OpenAI, Anthropic, etc.), every file the agent reads is sent to that provider. Ollama keeps everything on-box.

10. Screenshots

Home — 'Let's Start Building': open a repository or start from scratch.

Settings → LLM: Custom Model ollama/qwen2.5-coder:14b against a local Ollama at http://<LAN-IP>:11434/v1 — no API key required.

Settings → Application: built-in language picker (English, 日本語, 中文, 한국어, Norsk, Arabic…).

11. Contributing / License

Pull requests welcome. Issues: https://github.com/junkerderprovinz/unraid-apps/issues.

CI runs XML validation, an Unraid CA sanity check, markdown + YAML lint and a link check on every PR — see .github/workflows/ci.yml.

Licensing — dual:

• This wrapper repository (Unraid template, README, banner/icon artwork) is licensed under the MIT License.
• OpenHands itself is developed by the OpenHands community and retains its upstream license — see https://github.com/OpenHands/OpenHands. When you run, redistribute or rebuild the resulting container image, you must comply with all upstream licenses, not only with this wrapper's MIT license.

Credits

• OpenHands — the team and community building the agent
• Ollama — for making local LLMs painless
• LiteLLM — for unifying every LLM API on the planet
• Unraid Community Applications — for being the best app store in self-hosting

12. Support this project

If this template saves you a setup hassle or a debug night, consider buying me a coffee: