Analytics cookies only (Google Analytics, PostHog). No ad networks, no cross-site tracking. See our privacy policy.
Updated Sep 2026
verified on Ubuntu 26.04 · Aug 2026Self-host OpenHands on your own VPS — an AI-powered software development agent that can write, debug, and refactor code with full access to your codebase.
OpenHands is an AI-powered software development agent. Unlike chat-based coding assistants that suggest code snippets, OpenHands can autonomously explore your codebase, write code, run tests, fix bugs, and refactor — all with full access to your files and terminal. It's like having an AI pair programmer that can actually do the work, not just suggest it.
The appeal is autonomous development. OpenHands doesn't just generate code — it can understand your project structure, run your tests, debug failures, and iterate until the code works. It operates in a sandboxed environment with terminal access, so it can install dependencies, run linters, and execute scripts.
For teams, OpenHands can handle routine tasks: fixing lint errors, writing tests for existing code, updating dependencies, or implementing straightforward features. It's not a replacement for senior developers, but it can free them from repetitive work.
OpenHands runs in a Docker container with a full development environment. The agent itself is a Python application that communicates with an LLM backend, but the sandboxed workspace needs enough resources to build and run code.
OpenHands agent (UI + orchestration):
Sandboxed workspace:
LLM backend: Add the backend requirements on top. If using OpenAI/Anthropic, just the API calls. If using local Ollama, add the Ollama RAM requirements.
The practical minimum is 4 GB RAM with a cloud API backend, and 16 GB RAM if you're running Ollama locally. A 2 vCPU / 4 GB VPS works for lightweight use; for serious development work, you need at least 8 GB — 4 vCPU / 8 GB is the floor.
Start from a fresh Ubuntu 24.04 or 26.04 server. Update and create a non-root user:
apt update && apt upgrade -y
adduser deploy
usermod -aG sudo deploy
Lock down the firewall:
ufw allow OpenSSH
ufw allow 80
ufw allow 443
ufw enable
Install Docker (OpenHands runs in a container):
curl -fsSL https://get.docker.com | sh
usermod -aG docker deploy
Log out and back in as deploy so the docker group takes effect.
Paid link — we earn a commission if you shop through it.
Create a working directory:
mkdir ~/openhands && cd ~/openhands
Create a .env file with your LLM configuration:
cat > .env <<EOF
# LLM Backend (choose one)
# Option 1: OpenAI
LLM_MODEL=gpt-4
LLM_API_KEY=sk-your-key-here
# Option 2: Anthropic
# LLM_MODEL=claude-3-5-sonnet-20241022
# LLM_API_KEY=sk-ant-your-key-here
# Option 3: Ollama (local)
# LLM_MODEL=ollama/llama3.1
# LLM_BASE_URL=http://host.docker.internal:11434
# Security
SANDBOX_RUNTIME_CONTAINER_IMAGE=ghcr.io/all-hands-ai/runtime:0.14-nikolaik
WORKSPACE_DIR=/home/openhands/workspace
EOF
Create a compose file:
services:
openhands:
image: ghcr.io/all-hands-ai/openhands:latest
restart: unless-stopped
ports:
- "127.0.0.1:3000:3000"
volumes:
- openhands_workspace:/home/openhands/workspace
- /var/run/docker.sock:/var/run/docker.sock
env_file:
- .env
extra_hosts:
- "host.docker.internal:host-gateway"
volumes:
openhands_workspace:
The Docker socket mount (/var/run/docker.sock) allows OpenHands to create sandboxed containers for its workspace. This is necessary for the agent to run code in isolation.
Start it:
docker compose up -d
OpenHands listens on port 3000. The 127.0.0.1 bind keeps it private.
OpenHands operates on a workspace directory. By default, it uses /home/openhands/workspace inside the container. You can mount your project code into this directory:
Option 1: Use the built-in workspace OpenHands creates a fresh workspace you can work in directly. Good for new projects or experimentation.
Option 2: Mount an existing project Edit the compose file to mount your project:
volumes:
- /path/to/your/project:/home/openhands/workspace
- /var/run/docker.sock:/var/run/docker.sock
Option 3: Clone a repository OpenHands can clone Git repositories into its workspace. Use the web interface to clone your project and start working on it.
OpenHands needs HTTPS for production use, especially if you're accessing it remotely. Point a reverse proxy at 127.0.0.1:3000 and terminate HTTPS on 443.
The simplest path is Automatic HTTPS with Caddy. Point an A record for your hostname (say ai.example.com) at the server's public IP, then have Caddy reverse-proxy that hostname to 127.0.0.1:3000.
If you're using the Caddy container approach, put OpenHands and Caddy in the same compose file and proxy to the OpenHands service name:
reverse_proxy openhands:3000
Load https://ai.example.com in your browser. OpenHands shows a chat interface where you can describe what you want to build or fix.
Try a simple task:
Key features to test:
The agent has full terminal access in its sandbox, so it can install packages, run linters, execute tests, and even start servers.
OpenHands runs with Docker socket access, which gives it significant power. For production use:
Restrict access:
Sandbox isolation:
API key security:
OpenHands stores conversations and workspace data in the data volume:
docker run --rm -v openhands_workspace:/data -v $(pwd):/backup alpine \
tar czf /backup/openhands-$(date +%F).tar.gz -C /data .
For your project code, back up the source repository separately — OpenHands' workspace is a working copy, not the canonical source.
Pull the newer image and recreate:
docker compose pull
docker compose up -d
OpenHands updates may include new features or improved agent capabilities. Check the OpenHands changelog for breaking changes.
Agent can't access terminal. Verify the Docker socket is mounted correctly (/var/run/docker.sock). Check OpenHands logs for Docker connection errors.
Agent runs out of memory. The sandboxed container needs enough RAM for the project's build process. Increase the host's RAM or use a smaller model that requires less memory for context.
API key errors. Verify your LLM API key is valid and has credits. For OpenAI, check platform.openai.com. For Anthropic, check console.anthropic.com.
Slow responses. Expected with larger models or complex tasks. The agent makes multiple API calls per task (exploration, planning, coding, testing), so each interaction can take longer than a simple chat.
Can't clone repositories. Check that Git is available in the sandbox and that the repository URL is accessible from the server. For private repos, you may need to configure SSH keys or access tokens.
Docker permission errors. The deploy user needs to be in the docker group. Log out and back in after adding the user to the group.
You're done when you can: load the web interface over HTTPS, start a conversation, have the agent explore your codebase, write code, run tests, and produce working results. The agent should be able to install dependencies and execute commands in its sandbox.
From here, explore OpenHands' advanced features like multi-file editing, automated testing, and integration with your development workflow. For simpler code assistance without autonomous execution, see LibreChat. For document-based AI workflows, see AnythingLLM. A 4 vCPU / 8 GB box handles lightweight development; for serious projects, you need at least 8 GB RAM. See Best VPS for AI & ML Workloads for the ranked picks.
We estimate about 40 minutes of hands-on time for "How to Deploy OpenHands on a VPS"; this is an editorial estimate, not a measurement.
The "How to Deploy OpenHands on a VPS" guide was verified end-to-end on Ubuntu 26.04 (Aug 2026).