How to Deploy OpenHands on a VPS

copyapt update && apt upgrade -y
adduser deploy
usermod -aG sudo deploy

copyufw allow OpenSSH
ufw allow 80
ufw allow 443
ufw enable

copycurl -fsSL https://get.docker.com | sh
usermod -aG docker deploy

#Install OpenHands

Create a working directory:

copymkdir ~/openhands && cd ~/openhands

Create a .env file with your LLM configuration:

copycat > .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:

copyservices:
  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:

copydocker compose up -d

OpenHands listens on port 3000. The 127.0.0.1 bind keeps it private.

#Configure the workspace

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:

copyvolumes:
  - /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.

#HTTPS + domain

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

#First-run setup

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:

1. Start a new conversation
2. Describe a task: "Create a simple Python web server with FastAPI that serves a hello world endpoint"
3. Watch OpenHands explore, write code, install dependencies, and run the server

Key features to test:

• Code exploration — ask OpenHands to explain your codebase structure
• Bug fixing — describe a bug and watch it debug and fix it
• Test writing — ask it to write tests for existing code
• Refactoring — describe what you want to improve and watch it refactor

The agent has full terminal access in its sandbox, so it can install packages, run linters, execute tests, and even start servers.

#Security considerations

OpenHands runs with Docker socket access, which gives it significant power. For production use:

Restrict access:

• Use strong authentication (enable the built-in login)
• Limit who can access the web interface
• Consider running it behind a VPN for internal use

Sandbox isolation:

• OpenHands runs code in isolated Docker containers
• The workspace is separated from the host filesystem
• Terminal commands run in the sandbox, not on the host

API key security:

• Use environment variables, not hardcoded keys
• Consider using a key rotation strategy
• Monitor API usage for unexpected spikes

#Backups

OpenHands stores conversations and workspace data in the data volume:

copydocker 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.

#Upgrades

Pull the newer image and recreate:

copydocker compose pull
docker compose up -d

OpenHands updates may include new features or improved agent capabilities. Check the OpenHands changelog for breaking changes.

#Troubleshooting

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.

#Verification + next steps

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.