Running OpenHands on Proxmox

What this article covers

• What OpenHands is and when to use it.
• How to install OpenHands on Proxmox VE in an LXC container or VM.
• Resource requirements.
• Connecting OpenHands to local or hosted LLMs.
• Security considerations and common pitfalls.

Introduction: OpenHands on Proxmox

OpenHands is an open-source framework for AI-driven software development. It enables agents that can read files, write code, execute commands, and work with version control. Running OpenHands on Proxmox gives you isolation, snapshots, and straightforward resource management. A dedicated LXC or VM keeps OpenHands separate from the rest of your network.

OpenHands can connect to local models via Ollama or to hosted APIs such as OpenAI, Anthropic, and many others. Since agents actually execute code, an isolated environment is especially important.

What is OpenHands?

OpenHands is a coding agent framework. It offers:

• Code editing: Agents can read and modify files.
• Shell execution: Run commands in a sandbox.
• Version control: Work with Git repositories.
• LLM integration: Connect to many providers via LiteLLM.
• Web interface: Browser-based UI for interaction.
• Extensibility: Support for MCP servers and skills.

OpenHands is designed for developers who want to automate recurring coding tasks such as refactoring, bug fixes, or documentation.

LXC or VM?

LXC

• Advantages: Low overhead, fast startup, simple management.
• Disadvantages: Shares the kernel with the host, Docker in LXC requires elevated privileges.
• Recommended for: Dedicated LXC with Docker socket access and restricted filesystem scope.

VM

• Advantages: Own kernel, better isolation, simpler Docker operation.
• Disadvantages: More overhead.
• Recommended for: Higher security and GPU passthrough.

For getting started, an LXC is sufficient. If you want maximum isolation or plan to pass through a GPU, use a VM.

Hardware requirements

• CPU: 4 vCPUs minimum, 8 vCPUs recommended.
• RAM: 8 GB minimum, 16 GB recommended, 32 GB for larger models.
• Disk: 40 GB minimum, 80 GB recommended, since Docker images and models consume space.
• GPU: Optional, accelerates LLM inference.
• Network: Internet access for Docker images and API providers.

Prerequisites

• Proxmox VE with LXC or VM support.
• Ubuntu 24.04 LTS as guest OS.
• Docker and Docker Compose installed.
• An LLM provider or local Ollama instance.
• Optional: Tailscale or VPN for secure remote access.

Installation in an LXC

1. Create the LXC

pct create 400 ubuntu-24.04-standard_24.04-1_amd64.tar.zst \
  --hostname openhands \
  --storage local-zfs \
  --rootfs 80 \
  --memory 16384 \
  --cores 4 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp

If you plan to use Docker in the LXC, the container profile must have keyctl=1 and nesting=1:

pct set 400 --features keyctl=1,nesting=1

2. Install Docker

pct start 400
pct exec 400 -- bash
apt update && apt upgrade -y
apt install -y curl ca-certificates gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
usermod -aG docker root

3. Start OpenHands with Docker

mkdir -p ~/.openhands /projects
docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -v /projects:/projects \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8

OpenHands is then accessible at http://<lxc-ip>:3000.

Installation with uv

Alternatively, install OpenHands directly using uv:

apt install -y pipx
pipx install uv
uv tool install openhands --python 3.12

Start it:

openhands serve

This approach runs without Docker but forgoes sandbox isolation.

LLM Integration

Ollama locally

If Ollama runs in another LXC or on the same host, connect OpenHands via the internal IP:

http://192.168.1.50:11434

In OpenHands settings, select ollama as the provider and choose a model such as qwen2.5-coder:14b or codestral.

External provider

For OpenAI, Anthropic, DeepSeek, or OpenRouter, enter the API key in the settings. LiteLLM handles the communication.

Workspace and projects

The /projects directory in the container serves as the workspace in OpenHands. You can clone repositories or upload files. The agent then works in this directory.

cd /projects
git clone https://github.com/YOUR_USERNAME/repo.git

Security

OpenHands can execute shell commands. Proceed with caution:

• Isolated LXC or VM: No direct access to the Proxmox host.
• Enable sandboxing: Use Docker containers for agents.
• Filesystem restrictions: Mount only /projects and necessary paths.
• No root privileges: Do not run OpenHands as root.
• Network segmentation: Use Tailscale or firewall rules to control access.
• Protect API keys: Store them in a .env file or secret manager.
• Snapshots before critical tasks: Back up the state.

Workflow integration

• Configure Git: Set name and email in the container.
• SSH keys: For accessing private repositories.
• VS Code Tunnel: For direct editing of agent output.
• CI integration: Process results in GitHub Actions or GitLab CI.

Common pitfalls

• Docker socket errors: LXC needs nesting=1 and Docker privileges.
• Insufficient RAM: Agent server images are large; 8 GB is barely enough.
• Wrong model: Not every model is suitable for coding agents.
• No GPU: Longer wait times with larger models.
• Missing network isolation: Containers can contact external services.
• Incorrect Ollama URL: Use the /v1 endpoint when OpenHands speaks OpenAI-compatible protocol.

Further resources

• BotServ.de OpenClaw on Proxmox
• BotServ.de Proxmox Backups and Restore
• BotServ.de Proxmox Basics
• BotServ.de Tailscale Basics
• BotServ.de Managing Ollama

FAQ: OpenHands on Proxmox

Do I need a GPU? No, but for larger models or faster responses, it’s very helpful.

Can I run OpenHands in Docker on Proxmox? Yes, either in an LXC with Docker or directly in a VM.

Is OpenHands secure? Only if it runs isolated with sandboxing. Shell access is always a risk.

Which model works best? Coding models such as Qwen 2.5 Coder, DeepSeek-Coder, or Codestral.

Can OpenHands work with Git? Yes, it can clone repos, make changes, and create commits.

Sources and further reading

• OpenHands Docs: https://docs.openhands.dev/
• OpenHands GitHub: https://github.com/All-Hands-AI/OpenHands
• LiteLLM: https://docs.litellm.ai/

Summary: OpenHands on Proxmox

OpenHands is a powerful coding agent framework that runs well isolated in a Proxmox LXC or VM. The key requirements are adequate RAM, Docker sandboxing, correct LLM integration, and strong network and filesystem boundaries. Combine OpenHands with Ollama or an affordable external provider, and you get a standalone assistant for development tasks that stays within your own network.