Tutoriais de VPS
OpenHands Agent Canvas no VPS: SSH, modelos e backup (2026)
Instale Node.js 24, uv e Canvas no VPS Ubuntu de desenvolvimento, proteja backend com chave/túnel, configure modelos e valide sessões, backup, atualização e permissões.

Antes de seguir tutorial OpenHands, confira versão/interface: muitos exemplos docker run ... openhands:latest -p 3000:3000 são do Local GUI antigo. Aqui usamos Agent Canvas, interface web atual, com instalação VM oficial e túnel SSH, sem publicar backend diretamente.
É para uma pessoa, VPS Ubuntu dedicado ao desenvolvimento e modelos API cloud. Backend executa comandos, lê/escreve host e usa credenciais salvas. Essa rota roda no host; não é sandbox Docker. Afaste dados/chaves produtivos. Para contêineres, veja rota Docker.
Exemplo oficial começa com 2 vCPU e 4 GB RAM no Ubuntu 24.04 LTS. Builds grandes, testes e bancos exigem recursos adicionais medidos. Modelo cloud não precisa de GPU. Requisitos: Node.js 24+, npm, uv, Git e curl; veja requisitos oficiais.
Confira SSH do computador e depois recursos no VPS:
ssh [email protected]
free -h
df -h "$HOME"
uname -m
Troque IP de documentação. Restrinja SSH a administração/VPN e mantenha 8000 fechado externamente. Confira disco, portas, usuários e serviços existentes; prefira desenvolvimento separado da produção.
Use usuário SSH comum. Instalação precisa de sudo para dependências/npm global, mas rode agent-canvas sem sudo. Para mais separação, administrador instala e conta sem sudo executa. Exemplo 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
Revise scripts remotos antes. Pule Node 24/uv compatíveis existentes. node --version deve ser pelo menos 24. Conforme diagnóstico, agent-canvas: command not found costuma indicar binário global fora de PATH; confira npm list -g --depth 0/npm prefix -g, sem reinstalação cega.
Use --public com LOCAL_BACKEND_API_KEY forte. Isso exige autenticação no navegador, não abertura pública. Gere arquivo privado uma vez:
umask 077
printf 'export LOCAL_BACKEND_API_KEY=%s\n' "$(openssl rand -hex 32)" > "$HOME/.agent-canvas.env"
chmod 600 "$HOME/.agent-canvas.env"
Guarde no gerenciador, sem Git/chamados/conversas. cat ~/.agent-canvas.env apenas em terminal privado. Inicie tmux:
tmux new -s canvas
source "$HOME/.agent-canvas.env"
agent-canvas --public
Espere iniciar e desanexe com Ctrl-b, d. Ao reconectar, tmux attach -t canvas volta a sessão/logs. tmux mantém processo após queda, sem autoinício após reboot. Confira listener ss -ltnp | grep ':8000' e firewall 8000. Se escuta em todas as interfaces, restrinja explicitamente.
No seu computador, mantenha túnel:
ssh -N -L 8000:127.0.0.1:8000 [email protected]
Abra http://127.0.0.1:8000 com LOCAL_BACKEND_API_KEY. 127.0.0.1 é loopback do seu computador, ligado por SSH criptografado. Se 8000 ocupado, troque esquerda para 18000:127.0.0.1:8000 e abra http://127.0.0.1:18000. Confira identidade SSH/listener local privado. Sem túnel não há acesso web.
Chave protege execução API mesmo se alguém alcança porta. Backend acessa arquivos, rede e segredos; não publique 8000 direto. Para mais usuários, lista de segurança exige HTTPS, identidade e restrição de rede, não só porta/chave.
Canvas não inclui quota cloud. Em Settings > LLM, escolha Basic, provedor/modelo autorizado e API key. Salve e crie sessão nova; peça explicação README/plano em teste. Confira IDs/permissões/preços; use controles de gasto/alertas disponíveis, sem presumir bloqueio automático. Configuração inclui Advanced para serviços compatíveis OpenAI e LiteLLM.
- Login Codex/Claude/Gemini do notebook não migra automaticamente ao backend. Configure ACP no VPS por documentação.
- Arquivos dependem de conta/backend e permissões. Comece em teste, confira caminho/branch/custo, depois escrita. VS Code Remote SSH ajuda a revisar mudanças.
Pare ou estabilize processo antes de arquivar estado mutável; anote versão e copie projetos separadamente. Configurações/chaves/sessões normalmente ficam em ~/.openhands; confirme diretório:
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
Arquivo inclui key: restrinja, copie para fora e teste restauração. Git precisa de backup próprio. Pare com Ctrl+C, siga atualização com sudo npm install -g @openhands/agent-canvas@latest, reinicie usando arquivo de chave existente e valide sessões. Não regenere LOCAL_BACKEND_API_KEY só por atualizar.
| Sintoma | Conferir | Ação |
|---|---|---|
Falta agent-canvas | npm list -g --depth 0, npm prefix -g | Caminho bin em PATH |
Falta uv/uvx | uv --version, echo "$PATH" | Carregue ~/.local/bin/env e reinicie |
| Navegador não conecta | ss -ltnp remoto e túnel | Serviço ativo, túnel e porta local livre |
| UI abre, backend cai | Endereço e LOCAL_BACKEND_API_KEY | Backend/key corretos; endereço do túnel, não IP pública |
| Modelo falha | Provedor/modelo/key Settings > LLM | Permissões, quota/saldo e saída |
| VPS lento/disco cheio | free -h, df -h, builds | Reduza concorrência e identifique antes de limpar |
Se terminal basta, Codex CLI VPS pode ser mais leve. Canvas serve a navegador/backend permanente: defina antes acesso a arquivos e chaves.
Referências: VM, arquitetura/execução, modelo e diagnóstico.