Self-host OpenHands

Install#

Deploy installs Agent Canvas, runs it as a service with Docker sandboxes and an API key, connects a model, and checks that a sandboxed conversation answers. To do it yourself:

ssh exe.dev new --name=my-openhands
ssh my-openhands.exe.xyz

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
npm config set prefix ~/.local
npm install -g @openhands/agent-canvas@1.40.0
export PATH="$HOME/.local/bin:$PATH"
agent-canvas --version

sudo systemctl enable --now docker.service
docker pull ghcr.io/openhands/agent-server:1.62.0-python

mkdir -p ~/.config/agent-canvas
install -m 600 /dev/null ~/.config/agent-canvas/env
cat > ~/.config/agent-canvas/env <<EOF
LOCAL_BACKEND_API_KEY=$(openssl rand -hex 32)
OH_CONVERSATION_RUNTIME=docker
OH_CONVERSATION_RUNTIME_SELECTABLE=1
OH_CONVERSATION_IMAGE=ghcr.io/openhands/agent-server:1.62.0-python
EOF

sudo tee /etc/systemd/system/agent-canvas.service >/dev/null <<EOF
[Unit]
Description=OpenHands Agent Canvas
After=network-online.target docker.service
Wants=network-online.target docker.service

[Service]
User=$USER
WorkingDirectory=$HOME
EnvironmentFile=$HOME/.config/agent-canvas/env
Environment=PATH=$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=$HOME/.local/bin/agent-canvas --public --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now agent-canvas

until curl -sf -o /dev/null localhost:8000/; do sleep 2; done
systemctl is-active agent-canvas
curl -s -o /dev/null -w '%{http_code}\n' localhost:8000/api/settings

set -a; . ~/.config/agent-canvas/env; set +a
oh() { curl -fsS -H "X-Session-API-Key: $LOCAL_BACKEND_API_KEY" \
  -H 'Content-Type: application/json' "localhost:8000/api/$1" "${@:2}"; echo; }
LLM='{"llm":{"model":"anthropic/claude-sonnet-5-5","base_url":"https://llm.int.exe.xyz","api_key":"exe-gateway"}}'
oh profiles/claude-sonnet-5-5/validate -d "$LLM"
oh profiles/claude-sonnet-5-5 -d "$LLM"
oh profiles/claude-sonnet-5-5/activate -X POST
oh settings -X PATCH -d '{"conversation_settings_diff":{"default_runtime":"docker"}}' >/dev/null

mkdir -p ~/projects/hello && git -C ~/projects/hello init -q
agent=$(oh agent-profiles | jq -r .active_agent_profile_id)
id=$(oh conversations -d '{"agent_profile_id":"'"$agent"'",
  "workspace":{"working_dir":"'"$HOME"'/projects/hello"},
  "initial_message":{"role":"user","content":[{"type":"text",
  "text":"Create hello.py that prints 6*7 and run it. Reply with its output only."}]}}' | jq -r .id)
until oh conversations/$id | jq -e '.execution_status == "finished"' >/dev/null; do sleep 5; done
oh conversations/$id/agent_final_response
docker ps --format '{{.Names}} {{.Status}}'

Open OpenHands#

Port 8000 is private: only people with access to the VM get past exe.dev's login, and Agent Canvas asks for its API key on top. On your computer, print the key:

ssh my-openhands.exe.xyz "sed -n 's/^LOCAL_BACKEND_API_KEY=//p' .config/agent-canvas/env"

Open https://my-openhands.exe.xyz/ and log in to exe.dev. The page stays blank for a few seconds the first time, then Agent Canvas asks you to Add a backend. The host is already filled in. Give it a name, keep Local (it means a backend you run, not OpenHands Cloud), paste the key, and choose Next.

OpenHands then asks to Help improve OpenHands with Send anonymous usage data ticked; untick it if you'd rather not, and confirm. Keep OpenHands as the agent. Set up your LLM already shows the exe.dev profile from the install, so choose Next, then Close.

On the home screen, the chip under the message box says Docker. Choose Open Workspace, then + Add Workspace, pick projects under Favorites, and Add all subdirectories. Select hello, confirm, and give it a task:

Add index.html: a one-page site for a bakery that sells only sourdough. Keep it short, then commit it.

The agent sees the folder as /workspace, inside its own container. The panel on the right shows its files, changes, terminal and browser. Close the tab and come back later: the conversation keeps going on the VM. On a phone, open the same address, log in to exe.dev and add the backend the same way.

A few things worth knowing:

• Pick a model from the menu under the message box, or add one under Settings → LLM, Advanced tab. For exe.dev's gateway, use anthropic/claude-opus-5-5 with base URL https://llm.int.exe.xyz, openai/gpt-5.5 with https://llm.int.exe.xyz/v1, or fireworks_ai/accounts/fireworks/models/glm-5p3 with https://llm.int.exe.xyz/fireworks/inference/v1, and any text as the API key.
• Switch runtimes with the Docker chip, per conversation, or set the default under Settings → Runtime, which also sets the sandbox's memory and CPU limits. Worktree runs on the VM in a fresh Git worktree.
• Preview what it builds from a Local conversation: ask the agent to serve the app on 0.0.0.0:3000, then open https://my-openhands.exe.xyz:3000/. It's private until you share it. A Docker sandbox's ports stay inside its container.
• Set the commit author per project, since sandboxes start without your Git identity: git -C ~/projects/hello config user.name "Your Name" and user.email on the VM. The repository's own config is inside the mounted folder, so every runtime uses it.

Warning

Anyone with the API key who gets past exe.dev's login can run any command on the VM: the Local runtime is the VM. Keep the VM private, and only share it with people you'd give your SSH key to.

Sandboxes and the Docker socket#

Agent Canvas runs as you, and you are in the docker group, so the Agent Server can start containers. Membership in that group is as good as root on the VM. The sandboxes don't get the socket: each one mounts only its project folder, its conversation's state and a small home directory, runs as your user ID with no capabilities, and can't gain privileges. Don't add /var/run/docker.sock to a sandbox, and don't run Agent Canvas itself in a container with the socket mounted: either hands the agent the whole VM.

The sandbox limits what the agent can touch on disk, not what it can reach: containers share the VM's network, so they can reach exe.dev's LLM gateway and every integration attached to the VM. That's what lets a sandboxed agent push through a GitHub integration, and it's why each integration should cover only the repositories you want agents to have.

Bring your repositories#

There are two ways to give OpenHands GitHub, and they suit different jobs.

exe.dev's GitHub integration, for cloning, committing, pushing and the gh CLI. No GitHub token sits on the VM: exe.dev adds the credentials as requests leave it. Connect your GitHub account, then on your computer add a repository to the VM:

ssh exe.dev integrations add github --name your-repo --repository you/your-repo --attach vm:my-openhands

On the VM, clone it into ~/projects and add it as a workspace:

git clone https://github.int.exe.xyz/you/your-repo.git ~/projects/your-repo

The remote points at the integration, so the agent's pushes go through it, from a sandbox too. For gh, tell the agent to set GH_HOST=github.int.exe.xyz. Add --readonly to the integration for an agent that reads but never pushes, and --act-as-user to have pushes show as you instead of the exe.dev bot.

A GitHub token, for OpenHands' own GitHub features: the GitHub code review and GitHub issue to PR automations and the GitHub MCP server call GitHub's API with a token they read from Settings → Secrets. Make a fine-grained token for only the repositories they need, with an expiry, and save it there as the automation's setup asks. The trade-off: secrets are exported into every conversation's environment, so any agent run can read the token, and it's stored on the VM, encrypted with a key that sits next to it in ~/.openhands. Use the integration for everyday Git work, and a token only for the automations that need one.

Drive it from scripts#

The Agent Server behind Agent Canvas has a REST API, described at /openapi.json. On the VM, with the oh helper from Connect a model and check, start a conversation, wait for it, and read its answer as in the setup check. To ask from your computer instead, run the same commands over ssh my-openhands.exe.xyz; port 8000 is behind exe.dev's login, so scripts elsewhere can't reach it.

For work on a schedule, Automate in the sidebar runs a prompt or a script on a cron schedule, on the VM, with the same model and sandboxes.

Back up and restore#

Commit and push your code; that's the copy that matters most. For a copy of the whole VM, run this on your computer (choose a free backup name):

ssh exe.dev cp my-openhands my-openhands-backup

To keep OpenHands' settings and conversations on their own, archive them on the VM. The archive holds the API key and the key that decrypts saved secrets, so keep it private:

mkdir -p ~/backups
sudo systemctl stop agent-canvas
tar -C ~ -czf ~/backups/openhands-$(date +%F).tar.gz .openhands .config/agent-canvas projects
chmod 600 ~/backups/openhands-*.tar.gz
sudo systemctl start agent-canvas

Conversations started without a workspace keep their files in ~/workspace; add it to the tar command if you have it. To restore, on a VM installed as above, replace 2026-11-13 with the archive's date:

sudo systemctl stop agent-canvas
rm -rf ~/.openhands
tar -C ~ -xzf ~/backups/openhands-2026-11-13.tar.gz
sudo systemctl start agent-canvas

Your conversations are listed again, and browsers that know the old API key keep working.

Update#

On the VM, update Agent Canvas, then point the sandboxes at the Agent Server image it now expects:

npm install -g @openhands/agent-canvas@latest
v=$(agent-canvas --info | awk '$1 == "agent-server:" {print $2; exit}')
docker pull ghcr.io/openhands/agent-server:$v-python
sed -i "s|^OH_CONVERSATION_IMAGE=.*|OH_CONVERSATION_IMAGE=ghcr.io/openhands/agent-server:$v-python|" ~/.config/agent-canvas/env
sudo systemctl restart agent-canvas

Restarting interrupts running conversations, so pick a quiet moment. OpenHands releases every few days; read the release notes first. Each old sandbox image takes 5.5 GB: list them with docker image ls and remove the ones you're done with with docker image rm.

Troubleshooting#

• The page stays blank. Give it ten seconds the first time. If it still doesn't load, on the VM run systemctl status agent-canvas and journalctl -u agent-canvas -n 80 --no-pager; ss -ltn | grep 8000 should show 0.0.0.0:8000.
• Adding the backend fails. The key is wrong or has a stray space: print it again with the command from "Open OpenHands". The host must be https://my-openhands.exe.xyz, with no port.
• "Creating conversation…" never ends. The sandbox image is missing or still downloading: docker image ls should list the tag in ~/.config/agent-canvas/env. docker ps -a and docker logs <container> show a sandbox that started and stopped.
• A model fails. Run the validate call from Connect a model and check with that model's name and base URL; its error says what's wrong.
• The disk fills up. docker system df shows what Docker holds. Remove old sandbox images, or grow the disk with ssh exe.dev resize my-openhands --disk=50GB on your computer, then sudo resize2fs $(findmnt -no SOURCE /) on the VM.
• Sandboxes are slow or get killed. Each may use 4 GB and 2 CPUs. Lower the limits under Settings → Runtime, or resize the VM.
• agent-canvas: command not found. Open a new shell, or use ~/.local/bin/agent-canvas.

For everything else, see OpenHands' Docker runtime guide and VM guide.