Self-host OpenHands on a VPS

What OpenHands is, and the one risk to understand first

OpenHands, formerly OpenDevin, is an autonomous software-engineering agent. You give it a task in plain language, and it plans the work, writes code, runs commands, reads the output, and iterates until the task is done. You run it on your own server with Docker and point it at a language model. On a VPS it becomes a coding agent that works while you are away.

One fact should shape your whole setup. OpenHands does not just suggest code, it runs it, and to do that its controller container mounts the host Docker socket at /var/run/docker.sock so it can spawn sandbox containers for each task. Anything that can talk to the Docker socket can start a new container that mounts your entire host filesystem, which means socket access is effectively root on the machine. So treat the OpenHands box as a server that runs untrusted code, because that is exactly what it does. Every hardening choice below follows from that.

What you need

You need a VPS running Ubuntu 24.04 with a recent Docker Engine, at least 4 GB of RAM, and an API key for a language model (OpenAI, Anthropic, or Google), or a local model served by Ollama on the same VPS. OpenHands supports dozens of model backends, so the choice is yours. If you have never set up containers before, the basics of Docker on a VPS cover the ground this guide assumes.

Install with Docker

OpenHands ships as two images: the application image you run, and an agent-server image it pulls to run each task's sandbox. Run it like this, substituting the current tags from the project's 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 details save you an hour of confusion. The app image and the agent-server image carry different version numbers on purpose, so do not try to make them match: use the agent-server tag the docs pair with your app version. And notice the -p 127.0.0.1:3000:3000 rather than -p 3000:3000. That single change is the difference between a Web UI only you can reach and one the whole internet can reach, which the next section is about.

Keep the Web UI off the public internet

OpenHands serves its interface on port 3000. That interface drives an agent that runs code, so publishing it to the internet hands anyone who finds it a remote path into a process that executes commands. Bind it to loopback, as the run command above does, and reach it from your laptop over an SSH tunnel:

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

Then open http://127.0.0.1:3000 on your own machine. The traffic rides your existing SSH session, and nothing new listens on the public internet. For a more permanent setup, put it behind a VPN instead. Either way, put a default-deny firewall in front of the box so nothing is exposed by accident, and remember that a firewall covering only IPv4 leaves the same port open on IPv6, which is the IPv6 firewall gap that catches so many people.

Isolate the model key and any repo credentials

OpenHands needs an API key for its model, and often a token to clone and push to your repositories. Both can spend money and act as you, so treat them like passwords. Keep them in an environment file that only the right account can read, never in the run command where they land in your shell history and the process list, and never in a file inside a git repository.

Run it on a box you can throw away

Because the controller must hold the Docker socket, you cannot fully sandbox OpenHands away from its host. The honest mitigation is isolation by placement: run OpenHands on a dedicated VPS that holds nothing else you care about, not on the server that also runs your database or your website. Take a snapshot before you start, and rebuild from that snapshot rather than trusting a box that has run agent-authored code for a week. A cheap, disposable, single-purpose VPS is the right home for it.

Harden the box around it

The rest is standard server hygiene, and it matters more here than usual because the workload is riskier than usual. Create an unprivileged admin user rather than working as root, following running services as an unprivileged user. Move SSH to key-only authentication. Then run the checklist below and keep it somewhere you will see it again.

To understand the moving parts rather than just run them, see building your own AI agent on a VPS; for a lower-code platform, self-hosting Dify is a gentler on-ramp.

FAQ

Is OpenHands safe to run on a server?

It can be, with care, but it is riskier than an ordinary web app because it writes and runs code and its controller holds the host Docker socket, which is effectively root on the machine. Run it on a dedicated, disposable VPS that holds nothing else valuable, keep its Web UI on loopback behind an SSH tunnel or VPN, isolate its keys, and harden the box. Do not run it beside your important services.

Why does OpenHands need the Docker socket?

OpenHands runs each task in a fresh sandbox container, and it asks the host Docker daemon to create those containers by mounting /var/run/docker.sock into its controller. That gives the controller container control over Docker on the host, which is powerful and risky, so the host itself must be treated as one that runs untrusted code.

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

Yes. OpenHands supports local models served by Ollama or vLLM, so you can run it fully self-hosted with no per-token cost and no data leaving your server. You need a machine with enough memory for a capable coding model, which is the same sizing question covered in the Ollama guide.

Should I run OpenHands on my main server?

No. Because it runs agent-authored code and holds the Docker socket, keep it on a separate, single-purpose VPS you are willing to rebuild. Co-locating it with a database, a website, or your other services means a mistake by the agent, or a bug in it, can reach things it was never meant to touch.