Tutoriales de VPS
OpenHands Agent Canvas en VPS: SSH, modelos y copias (2026)
Instala Node.js 24, uv y Canvas en VPS Ubuntu de desarrollo, protege backend con clave y túnel, configura modelos y verifica sesiones, copias, actualizaciones y permisos.

Antes de seguir un tutorial OpenHands, identifica versión e interfaz: muchos ejemplos docker run ... openhands:latest -p 3000:3000 corresponden al Local GUI antiguo. Aquí usamos Agent Canvas, la interfaz web actual, con despliegue VM oficial y túnel SSH, sin publicar backend directamente.
Se dirige a una persona, VPS Ubuntu de desarrollo dedicado y modelos API cloud. Backend ejecuta comandos, lee/escribe host y usa credenciales guardadas. Esta ruta corre en host; no es sandbox Docker. No pongas secretos/datos productivos. Para contenedores, revisa ruta Docker.
El ejemplo oficial empieza con 2 vCPU y 4 GB RAM en Ubuntu 24.04 LTS. Builds grandes, pruebas y bases requieren recursos medidos adicionales. Modelo cloud no exige GPU. Requisitos: Node.js 24+, npm, uv, Git y curl; mira requisitos oficiales.
Verifica SSH desde tu ordenador y después recursos del VPS:
ssh [email protected]
free -h
df -h "$HOME"
uname -m
Sustituye IP de documentación. Restringe SSH a administración/VPN y mantén 8000 cerrado externamente. Revisa disco, puertos, usuarios y servicios existentes; prefiere desarrollo separado de producción.
Usa usuario SSH normal. Instalación requiere sudo para dependencias/npm global, pero ejecuta agent-canvas sin sudo. Para más separación, administra instalación y usa cuenta de ejecución sin sudo. El ejemplo Ubuntu usa 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
Inspecciona scripts remotos antes. Omite Node 24/uv compatibles existentes. node --version debe ser al menos 24. Según diagnóstico, agent-canvas: command not found suele significar binario global fuera de PATH; revisa npm list -g --depth 0/npm prefix -g, no reinstales a ciegas.
Usa --public con LOCAL_BACKEND_API_KEY fuerte. Exige autenticación del navegador, no abrir internet. Genera una vez archivo privado:
umask 077
printf 'export LOCAL_BACKEND_API_KEY=%s\n' "$(openssl rand -hex 32)" > "$HOME/.agent-canvas.env"
chmod 600 "$HOME/.agent-canvas.env"
Guarda en gestor, sin Git/tickets/chat. cat ~/.agent-canvas.env solo en terminal privado. Inicia tmux:
tmux new -s canvas
source "$HOME/.agent-canvas.env"
agent-canvas --public
Espera inicio y separa con Ctrl-b, d. Al reconectar, tmux attach -t canvas vuelve a sesión/logs. tmux conserva proceso tras desconexión, sin autoinicio después de reboot. Mira listener ss -ltnp | grep ':8000' y firewall 8000. Si escucha en todas las interfaces, restringe esa exposición explícitamente.
En tu ordenador, mantén este túnel:
ssh -N -L 8000:127.0.0.1:8000 [email protected]
Abre http://127.0.0.1:8000 y usa LOCAL_BACKEND_API_KEY. 127.0.0.1 es loopback de tu equipo, conectado por SSH cifrado. Si 8000 local ocupado, cambia izquierda a 18000:127.0.0.1:8000 y abre http://127.0.0.1:18000. Verifica identidad SSH y listener local privado. Sin túnel no hay acceso web.
La clave protege ejecución API incluso si alguien alcanza puerto. Backend tiene acceso a archivos, red y secretos: no publiques 8000 directamente. Para más usuarios, lista de seguridad pide HTTPS, identidad y restricciones de red, no puerto/clave solos.
Canvas no incluye cuota cloud. En Settings > LLM, elige Basic, proveedor/modelo autorizado y API key. Guarda y crea sesión nueva; pide explicar README y proponer plan en repositorio de prueba. Verifica IDs/permisos/precios; usa controles de gasto y alertas disponibles, que no siempre bloquean gasto. Configuración incluye Advanced para servicios compatibles OpenAI y LiteLLM.
- Login Codex/Claude/Gemini del portátil no se traslada automáticamente al backend. Configura ACP en VPS según documentación.
- Archivos dependen de cuenta/backend y permisos. Empieza en prueba, revisa ruta/rama/coste y después escritura. VS Code Remote SSH ayuda a revisar cambios.
Detén o estabiliza proceso antes de archivar estado mutable; registra versión y copia proyectos aparte. Configuración, claves y sesiones suelen estar en ~/.openhands; confirma directorio:
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
El archivo incluye key: restringe, copia a almacenamiento externo y prueba recuperación. Git necesita copia propia. Detén proceso con Ctrl+C, sigue actualización usando sudo npm install -g @openhands/agent-canvas@latest, reinicia con archivo de clave existente y valida sesiones. No regeneres LOCAL_BACKEND_API_KEY solo por actualizar.
| Síntoma | Revisar | Acción |
|---|---|---|
Falta agent-canvas | npm list -g --depth 0, npm prefix -g | Ruta bin en PATH |
Falta uv/uvx | uv --version, echo "$PATH" | Carga ~/.local/bin/env y reinicia |
| Navegador no conecta | ss -ltnp remoto y túnel | Servicio activo, túnel y puerto local libre |
| UI abre, backend cae | Dirección y LOCAL_BACKEND_API_KEY | Backend/clave correctos; dirección del túnel, no IP pública |
| Modelo falla | Proveedor/modelo/key Settings > LLM | Permisos, cuota/saldo y salida |
| VPS lento/disco lleno | free -h, df -h, builds | Reduce concurrencia e identifica archivos antes de limpiar |
Si basta terminal, Codex CLI VPS puede ser más ligero. Canvas sirve para navegador/backend permanente: define primero acceso a archivos y secretos.
Referencias: VM, arquitectura/ejecución, modelo y diagnóstico.