VPS Tutorials
OpenHands Agent Canvas on a VPS: SSH, Models and Backups (2026)
Install Node.js 24, uv and Agent Canvas on an Ubuntu development VPS, protect backend access with a key and SSH tunnel, configure models and verify sessions, updates, backups and execution boundaries.

Before following an OpenHands VPS tutorial, identify its interface and version: many docker run ... openhands:latest -p 3000:3000 examples describe the older Local GUI. This guide uses the current Agent Canvas browser workbench and official VM setup, reached through SSH rather than a directly public backend port.
It covers one user, a dedicated Ubuntu development VPS and cloud model APIs. The backend can execute commands, read/write host files and use stored credentials. This VM route runs directly on the host; it is not a Docker sandbox. Keep production data and keys elsewhere. For container boundaries, review the Docker deployment route.
The official single-user example starts with 2 vCPU and 4 GB RAM on Ubuntu 24.04 LTS. Large builds, tests and databases need measured additional CPU, memory and disk. Cloud inference does not require a GPU VPS. Requirements include Node.js 24+, npm, uv, Git and curl; see official requirements.
Verify SSH from your computer, then inspect resources on the VPS:
ssh [email protected]
free -h
df -h "$HOME"
uname -m
Replace the documentation IP with your own. Permit SSH only from administrative IPs or a VPN range and keep port 8000 closed externally. Check existing services, disk, ports and permissions; a dedicated development machine is preferable to sharing a production host.
Use an ordinary SSH account. The installation examples need sudo for system dependencies/global npm, but run agent-canvas without sudo. For stronger separation, let an administrator install prerequisites and use a dedicated runtime account without sudo. The Ubuntu example uses NodeSource:
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg git tmux openssl
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"
sudo npm install -g @openhands/agent-canvas
node --version
uv --version
agent-canvas --version
Inspect remote installation sources before execution. Skip existing compatible Node.js 24 and uv installations. Check node --version is at least 24. The troubleshooting guide explains that agent-canvas: command not found often means npm's global binary path is absent from PATH; inspect npm list -g --depth 0 and npm prefix -g instead of repeatedly reinstalling.
Remote deployment uses --public with a strong LOCAL_BACKEND_API_KEY. This requires browser authentication; it is not a request to open the service to the internet. Generate a key once in a private file:
umask 077
printf 'export LOCAL_BACKEND_API_KEY=%s\n' "$(openssl rand -hex 32)" > "$HOME/.agent-canvas.env"
chmod 600 "$HOME/.agent-canvas.env"
Keep it in a password manager, outside Git, tickets and shared chat. View it only in a private terminal using cat ~/.agent-canvas.env. Start tmux:
tmux new -s canvas
source "$HOME/.agent-canvas.env"
agent-canvas --public
Wait for startup, then press Ctrl-b followed by d to detach. After reconnecting, use tmux attach -t canvas to inspect the original session/logs. tmux keeps the process after SSH disconnects but does not start it automatically after reboot. Check listeners with ss -ltnp | grep ':8000' and ensure the cloud firewall still blocks 8000. If listening on all interfaces, restrict that network exposure explicitly.
Keep this tunnel running in another terminal on your own computer:
ssh -N -L 8000:127.0.0.1:8000 [email protected]
Visit http://127.0.0.1:8000 and enter LOCAL_BACKEND_API_KEY. 127.0.0.1 is your computer's loopback, with traffic encrypted through SSH. If local port 8000 is occupied, change the left-hand port to 18000:127.0.0.1:8000 and visit http://127.0.0.1:18000. Verify SSH host identity and keep the local listener private. Browser access requires the active tunnel.
The key protects backend API execution even when a connection reaches the port. Do not expose 8000 directly: the backend can access host files, networking and secrets. For broader access, follow the security checklist with HTTPS, identity controls and network restrictions rather than relying on a bare port or key alone.
Agent Canvas does not include cloud-model quota. In Settings > LLM, choose Basic, select an entitled provider/model and enter its API key. Save, then create a new session and ask for a test README explanation and plan. Verify model IDs, permissions and prices with the provider. Use available spend controls and alerts; alerts may not impose hard limits. The model guide also describes Advanced for OpenAI-compatible services and LiteLLM proxies.
- Authentication on a laptop for Codex, Claude Code or Gemini CLI does not automatically authenticate the VPS backend. Configure ACP agents on the backend host according to ACP documentation.
- Files available to the agent depend on backend account and workspace permissions. Begin with a test repository and inspect path, Git branch and costs before writes. VS Code Remote SSH can help review remote changes.
Stop or quiesce the process before archiving mutable state, record its version and back up projects separately. Settings, keys and sessions commonly live under ~/.openhands; verify the actual directory exists:
agent-canvas --version
ls -ld "$HOME/.openhands" "$HOME/.agent-canvas.env"
umask 077
mkdir -p "$HOME/backups"
tar -C "$HOME" -czf "$HOME/backups/agent-canvas-$(date +%F).tgz" .openhands .agent-canvas.env
The archive includes the backend key. Restrict it, copy it to independent controlled storage and test readability/restoration. Git repositories need their own backups. Stop the old process with Ctrl+C, follow update guidance with sudo npm install -g @openhands/agent-canvas@latest, then restart using the existing key file and validate sessions. Do not regenerate LOCAL_BACKEND_API_KEY simply because the application updated.
| Symptom | Inspect first | Direction |
|---|---|---|
agent-canvas missing | npm list -g --depth 0, npm prefix -g | Global npm bin path in PATH |
Missing uv/uvx | uv --version, echo "$PATH" | Reload ~/.local/bin/env and restart |
| Local browser cannot connect | VPS ss -ltnp and tunnel terminal | Running backend, live tunnel and available local port |
| UI opens, backend disconnects | Backend address and LOCAL_BACKEND_API_KEY | Match active backend/key; use the tunnel address, not public VPS IP |
| Model error at session start | Settings > LLM provider/model/key | Entitlement, quota/balance and outbound network |
| Slow VPS or full disk | free -h, df -h, build artifacts | Reduce concurrency, identify files before cleanup/expansion |
If a terminal agent is enough, Codex CLI on a VPS may be a lighter fit. Agent Canvas suits a browser workbench with a persistent remote backend; first define host-file and credential boundaries.
References: VM setup, architecture and execution scope, model setup and troubleshooting.