OpenHands Deployment Guide on RamNode VPS

Prerequisites

Recommended VPS Specifications

Component	Recommendation
OS	Ubuntu 22.04 or 24.04 LTS
RAM	8 GB minimum (16 GB recommended for heavy workloads)
Storage	40 GB+ NVMe SSD (Docker images can be large)
CPU	2+ vCPU cores
Network	Stable internet connection with public IP

What You'll Need

A RamNode VPS with root/sudo access
SSH client (Terminal on macOS/Linux, PuTTY or Windows Terminal on Windows)
An API key from an LLM provider (Anthropic, OpenAI, Google, or OpenHands)
A domain name (optional, for HTTPS access with a reverse proxy)

💡 RamNode Plan Suggestion: A KVM VPS with 8 GB RAM and 80 GB NVMe storage is an excellent starting point. You can scale up later if you need more resources for parallel agent runs.

Initial Server Setup

Connect and update system

ssh root@YOUR_VPS_IP

# Update system packages
apt update && apt upgrade -y

# Install essential utilities
apt install -y curl wget git ufw software-properties-common

Create a non-root user

adduser openhands
usermod -aG sudo openhands
su - openhands

Configure the firewall

sudo ufw allow OpenSSH
sudo ufw allow 3000/tcp     # OpenHands Web UI
sudo ufw enable
sudo ufw status

Security Note: Port 3000 will expose the OpenHands UI to the internet without authentication by default. We strongly recommend setting up a reverse proxy with HTTPS and authentication (covered in Optional Enhancements).

Install Docker

Add Docker repository and install

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the Docker repository
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" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Post-installation: run Docker without sudo

sudo usermod -aG docker $USER
newgrp docker

# Verify the installation
docker --version
docker run hello-world

If docker run hello-world completes successfully with a greeting message, Docker is properly installed and your user has the correct permissions.

Deploy OpenHands

Option A: Using the CLI Launcher (Recommended)

The CLI launcher handles Docker image management, version checking, and configuration automatically.

Install and launch via CLI

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Install and Launch OpenHands
uv tool install openhands --python 3.12
openhands serve

Option B: Using Docker Directly

Run OpenHands container

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

Once started, OpenHands will be accessible at http://YOUR_VPS_IP:3000 in your web browser.

💡 First Launch: The first launch will take several minutes as Docker pulls the OpenHands and agent-server images (several GB in total). Subsequent launches will be much faster.

Configure OpenHands

LLM Provider Setup

Navigate to http://YOUR_VPS_IP:3000 in your browser.
On the initial settings popup (or click the gear icon), select your LLM Provider.
Choose your LLM Model from the dropdown.
Enter your API Key for the selected provider.

Supported LLM Providers

Provider	Notes
Anthropic (Claude)	Recommended. Top-tier agentic coding performance.
OpenAI (GPT-4o+)	Strong alternative with broad model selection.
Google (Gemini)	Good performance, competitive pricing.
OpenHands LLM	Purpose-built models optimized for agentic coding tasks.
Local via Ollama	Free, private. Requires additional GPU resources.

Web Search: To let the agent search the web for documentation and solutions, get a free API key from tavily.com and enter it under Settings → LLM tab → Search API Key (Tavily).

Run as a Background Service

Option A: Docker Compose (Recommended)

Create docker-compose.yml

mkdir -p ~/openhands && cd ~/openhands

docker-compose.yml

services:
  openhands:
    image: docker.openhands.dev/openhands/openhands:1.4
    container_name: openhands-app
    stdin_open: true
    tty: true
    pull_policy: always
    environment:
      - AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server
      - AGENT_SERVER_IMAGE_TAG=1.11.4-python
      - LOG_ALL_EVENTS=true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ~/.openhands:/.openhands
    ports:
      - "3000:3000"
    extra_hosts:
      - host.docker.internal:host-gateway
    restart: unless-stopped
    healthcheck:
      test: timeout 10s bash -c ':> /dev/tcp/127.0.0.1/3000' || exit 1
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 120s

Manage the service

# Start the service
docker compose up -d

# View logs
docker compose logs -f openhands

# Stop the service
docker compose down

Option B: Systemd Service

/etc/systemd/system/openhands.service

[Unit]
Description=OpenHands AI Coding Agent
Requires=docker.service
After=docker.service

[Service]
Type=simple
User=openhands
Restart=always
RestartSec=10
WorkingDirectory=/home/openhands/openhands
ExecStart=/usr/bin/docker compose up
ExecStop=/usr/bin/docker compose down

[Install]
WantedBy=multi-user.target

Enable and start

sudo systemctl daemon-reload
sudo systemctl enable openhands
sudo systemctl start openhands
sudo systemctl status openhands

Optional Enhancements

Secure with Nginx Reverse Proxy + SSL

Install Nginx and Certbot

sudo apt install -y nginx certbot python3-certbot-nginx

/etc/nginx/sites-available/openhands

server {
    listen 80;
    server_name your_domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 86400;
    }
}

Enable site and obtain SSL

sudo ln -s /etc/nginx/sites-available/openhands /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Obtain SSL certificate
sudo certbot --nginx -d your_domain.com

# Update firewall
sudo ufw allow 'Nginx Full'
sudo ufw delete allow 3000/tcp

WebSocket Support: The proxy_set_header Upgrade and Connection headers are critical. OpenHands uses WebSockets for real-time communication between the browser and the agent.

HTTP Basic Authentication

Add authentication layer

sudo apt install -y apache2-utils
sudo htpasswd -c /etc/nginx/.htpasswd your_username

# Add inside the Nginx location block:
# auth_basic "OpenHands";
# auth_basic_user_file /etc/nginx/.htpasswd;

Automatic Updates

Set up auto-update cron job

crontab -e

# Add: Pull latest images and restart weekly
0 3 * * 0 cd ~/openhands && docker compose pull && docker compose up -d

Using OpenHands

OpenHands provides a browser-based interface where you interact with the AI agent through natural language. Example tasks:

Build applications: "Create a FastAPI backend with user authentication and a PostgreSQL database."
Debug code: "Fix the failing test in tests/test_auth.py and explain what was wrong."
Refactor: "Refactor the monolithic app.py into a clean MVC architecture."
Write tests: "Generate comprehensive unit tests for the utils/ directory with 90%+ coverage."
DevOps tasks: "Create a Dockerfile and GitHub Actions CI/CD pipeline for this project."
Documentation: "Generate API documentation and a README for this repository."

The agent operates in a sandboxed Docker environment, so it can safely execute commands, install packages, and run code without affecting your host system.

Troubleshooting

Issue	Solution
Container fails to start	Check Docker socket permissions: `ls -la /var/run/docker.sock`. Ensure your user is in the docker group.
Port 3000 not accessible	Verify UFW rules (`sudo ufw status`) and check the container is running (`docker ps`).
Agent timeout errors	Increase server RAM. Complex tasks may require 16 GB+ for large context windows.
Docker pull fails	Check disk space (`df -h`). Clear old images with `docker system prune`.
WebSocket errors in browser	If using a reverse proxy, ensure the Upgrade and Connection headers are properly configured.

Useful Commands

Diagnostic commands

# Check container status
docker ps -a | grep openhands

# View real-time logs
docker logs -f openhands-app

# Restart the service
docker compose restart

# Check resource usage
docker stats openhands-app

OpenHands Deployed Successfully!

Your self-hosted AI coding agent is now running on RamNode. You have a private, always-available AI development partner that can autonomously write, debug, test, and deploy code.

Useful Resources

OpenHands Documentation: docs.openhands.dev
OpenHands GitHub: github.com/OpenHands/OpenHands
Docker Documentation: docs.docker.com

More Deployment Guides View Cloud VPS Plans

Deploying OpenHands