OpenHands is an open-source AI software engineer. Its web app, Agent Canvas, runs coding agents that read and write code, run commands and browse, and automations that run them on a schedule or from a webhook. It uses any model provider you give it a key for.
This template installs it on a Cubeship instance, with the web app on a domain and everything it keeps in two volumes.
- openhands — Agent Canvas
1.18.0, built on the instance from theDockerfilein this repository: the web app, the agent server and the automation backend in one container, answering on the domain you choose. Settings, secrets, conversations and automations are kept in a volume at/home/openhands/.openhands, and the code the agent works on in one at/projects.
It needs Cubeship 0.7.0 or newer, and an admin to install it: the app is built on the instance, and only admins build.
The published image, ghcr.io/openhands/agent-canvas, writes its API key into
the page it serves, so the browser is signed in without asking. That is meant
for a machine only you can reach; on a domain it would sign in anyone who opens
it. The Dockerfile here is that image with one flag changed, the one
OpenHands' own --public mode changes: the page asks for the key instead. The
build fails rather than ship the old behaviour if a new image stops matching.
| Input | What to give |
|---|---|
| Where OpenHands answers | A domain you control, pointed at your instance. |
| The API key you sign in with | Nothing — the instance generates it and shows it once. Keep a copy. |
No model provider key is asked for. Add one in the app instead: it is stored, encrypted, in the volume.
- Open the domain. It sends you to
/canvas, which asks for the API key: paste the generated one. - Under Settings, choose a model provider and enter its key.
- Start a conversation. The agent works in
/projects; clone a repository there, or add a GitHub token under Settings and let it clone one.
The API key is all that stands between the domain and an agent that runs any command in its container, with the model keys and tokens you gave it. OpenHands documents a firewall or an IP allow-list in front of it as well; Cubeship cannot restrict a domain by address, so keep the key long and to yourself.
The browser keeps the key in the page's storage. The built-in editor, at
/vscode on the same domain, can read that storage, which OpenHands tracks as
#16492.
To reach this instance from an Agent Canvas on your own machine, add it under Manage backends with the domain as its host and the API key.
The agent runs its commands inside the container, as the unprivileged
openhands user: the two volumes, the internet, and other apps on the instance
at their internal addresses. It has no Docker socket and no privileged mode, so
it cannot start containers, and OpenHands' Docker sandbox, which would give
each conversation a container of its own, does not work here.
The app runs as one copy on the machine its volumes are on, and a deploy stops it for a few seconds, ending any conversation in progress. Back both up from the app's settings. The key that encrypts stored secrets is generated on first start and kept in the first volume, so a backup of it restores them.
Agent Canvas sends anonymous usage events to OpenHands unless told otherwise.
Set AGENT_CANVAS_DISABLE_TELEMETRY=1 on the app and redeploy to turn off the
web app's.
Change the tag in the Dockerfile, release this repository, and point ref at
the new release.
The app is limited to 2 CPUs and 4 GiB of memory. The agent builds and tests
code in the same container, so raise limits in template.yaml for large
projects.
This is a template for Cubeship —
a PaaS you run on your own server: docker push, and it is live, with HTTPS,
a database beside it, and a second machine when one stops being enough.
Browse every template at cubeship.dev/templates.