how to install OpenHands for VPS

Wetin OpenHands be, and one risk wey you must know first

OpenHands, wey dem call am OpenDevin before, na autonomous software-engineering agent. You go give am task for simple English, and e go plan the work, write code, run commands, read the output, and continue work until the task finish. You go run am for your own server with Docker and connect am to one language model. If you run am for VPS, e go become coding agent wey dey work even when you no dey.

One thing must guide how you go set up everything. OpenHands no just dey suggest code, e dey run am, and to do that, its controller container mount the host Docker socket at /var/run/docker.sock so e fit spawn sandbox containers for every task. Anything wey fit talk to the Docker socket fit start new container wey go mount your entire host filesystem, wey mean say socket access na effectively root for the machine. So, treat the OpenHands box as one server wey dey run untrusted code, because na wetin e dey do exactly. Every hardening choice wey dey below follow from that one.

Wetin you need

You need VPS wey dey run Ubuntu 24.04 with recent Docker Engine, at least 4 GB of RAM, and API key for one language model (OpenAI, Anthropic, or Google), or one local model wey Ollama on the same VPS dey serve. OpenHands support many model backends, so the choice na yours. If you never set up containers before, the basics of Docker on a VPS go explain the ground wey this guide dey assume.

Install with Docker

OpenHands dey come with two images: the application image wey you go run, and agent-server image wey e go pull to run sandbox for each task. Run am like this, change the current tags for the project docs:

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 \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands \
  docker.openhands.dev/openhands/openhands:1.8

Two small things go save you one hour of confusion. The app image and agent-server image get different version numbers by design, so no try make dem match: use the agent-server tag wey the docs pair with your app version. And look for the -p 127.0.0.1:3000:3000 instead of -p 3000:3000. That single change na the difference between one Web UI wey only you fit reach and one wey the whole internet fit reach, wey na wetin the next section dey talk about.

Keep the Web UI off the public internet

OpenHands dey serve its interface for port 3000. That interface dey drive agent wey dey run code, so if you publish am to the internet, you dey give anyone wey find am remote path enter one process wey dey execute commands. Bind am to loopback, like the run command wey dey above, and reach am from your laptop through SSH tunnel:

ssh -L 3000:127.0.0.1:3000 you@your-vps

Then open http://127.0.0.1:3000 for your own machine. The traffic go follow your existing SSH session, and nothing new go dey listen for public internet. For one more permanent setup, put am behind VPN instead. Either way, put one default-deny firewall for front of the box so nothing go expose by accident, and remember say firewall wey only cover IPv4 go leave the same port open for IPv6, wey na the IPv6 firewall gap wey dey catch many people.

Isolate the model key and any repo credentials

OpenHands need API key for its model, and often one token to clone and push to your repositories. Both of dem fit spend money and act like you, so treat dem like passwords. Keep dem for one environment file wey only the right account fit read, no put dem for run command because dem go land for your shell history and the process list, and no put dem for inside any file for git repository.

Run it on a box wey you fit throw away

Because the controller must hold the Docker socket, you no fit fully sandbox OpenHands away from its host. The real way to reduce risk na isolation by placement: run OpenHands for one dedicated VPS wey no get any other thing wey you care about, no run am for the same server wey dey run your database or your website. Take one snapshot before you start, and rebuild from that snapshot instead of to trust one box wey don run agent-authored code for one week. One cheap, disposable, single-purpose VPS na the right home for am.

Harden the box around it

The rest na standard server hygiene, and e important pass normal because this workload riskier than usual. Create one unprivileged admin user instead of to work as root, follow running services as an unprivileged user. Move SSH to key-only authentication. Then run the checklist wey dey below and keep am somewhere wey you go see am again.

To understand how the parts dey work instead of to just run dem, see building your own AI agent on a VPS; for one low-code platform, self-hosting Dify go easy pass.

FAQ

Is OpenHands safe to run on a server?

E fit be safe if you take care, but e riskier than ordinary web app because e dey write and run code and its controller hold the host Docker socket, wey na effectively root for the machine. Run am for one dedicated, disposable VPS wey no get any other valuable thing, keep its Web UI on loopback behind SSH tunnel or VPN, isolate its keys, and harden the box. No run am beside your important services.

Why does OpenHands need the Docker socket?

OpenHands dey run each task for one fresh sandbox container, and e dey ask the host Docker daemon to create those containers by mounting /var/run/docker.sock into its controller. That one dey give the controller container control over Docker for the host, wey powerful and risky, so the host itself must be treated as one wey dey run untrusted code.

Can OpenHands use a local model instead of a paid API?

Yes. OpenHands support local models wey Ollama or vLLM dey serve, so you fit run am fully self-hosted without to pay for token and without to let data leave your server. You need one machine wey get enough memory for one capable coding model, wey na the same sizing question wey the Ollama guide cover.

Should I run OpenHands on my main server?

No. Because e dey run agent-authored code and e hold the Docker socket, keep am for one separate, single-purpose VPS wey you ready to rebuild. To put am for the same place as your database, website, or other services mean say if the agent make mistake, or if e get bug, e fit reach things wey e no suppose touch.