Como hospedar o OpenHands em um VPS com Docker

O que é o OpenHands e o único risco que deve compreender primeiro

O OpenHands, anteriormente chamado OpenDevin, é um agente autónomo de engenharia de software. Indica-lhe uma tarefa em linguagem corrente e ele planeia o trabalho, escreve código, executa comandos, lê o resultado e repete o processo até concluir a tarefa. Pode executá-lo no seu próprio servidor com Docker e ligá-lo a um modelo de linguagem. Num VPS, funciona como um agente de programação que trabalha enquanto está ausente.

Um facto deve orientar toda a configuração. O OpenHands não se limita a sugerir código: também o executa. Para isso, o seu contentor controlador monta o socket Docker do host em /var/run/docker.sock, para poder iniciar contentores sandbox para cada tarefa. Qualquer processo que consiga comunicar com o socket Docker pode iniciar um novo contentor com o sistema de ficheiros completo do host montado. Isto significa que o acesso ao socket equivale efetivamente a acesso root à máquina. Por isso, trate o servidor do OpenHands como um servidor que executa código não confiável, porque é exatamente isso que ele faz. Todas as medidas de hardening abaixo resultam deste facto.

O que precisa

Precisa de um VPS com Ubuntu 24.04, uma versão recente do Docker Engine, pelo menos 4 GB de RAM e uma chave de API para um modelo de linguagem (OpenAI, Anthropic ou Google), ou de um modelo local servido pelo Ollama no mesmo VPS. O OpenHands suporta dezenas de backends de modelos, por isso a escolha é sua. Se nunca configurou contentores, os conceitos básicos do Docker num VPS abrangem os conhecimentos pressupostos neste guia.

Instalar com Docker

OpenHands disponibiliza duas imagens: a imagem da aplicação que executa e uma imagem agent-server que descarrega para executar o sandbox de cada tarefa. Execute-o assim, substituindo as tags atuais indicadas na documentação do projeto:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands \
  docker.openhands.dev/openhands/openhands:1.8

Dois detalhes evitam uma hora de confusão. A imagem da aplicação e a imagem agent-server têm números de versão diferentes de propósito. Não tente fazê-los coincidir: use a tag agent-server associada à versão da aplicação na documentação. Repare também em -p 127.0.0.1:3000:3000, em vez de -p 3000:3000. Essa única alteração determina se apenas você consegue aceder à Web UI ou se toda a Internet consegue aceder-lhe. A próxima secção explica este ponto.

Mantenha a interface Web fora da internet pública

O OpenHands disponibiliza a sua interface na porta 3000. Essa interface controla um agente que executa código. Publicá-la na internet dá a qualquer pessoa que a encontre um caminho remoto para um processo que executa comandos. Ligue-a ao loopback, como faz o comando de execução acima, e aceda a ela a partir do seu portátil através de um túnel SSH:

ssh -L 3000:127.0.0.1:3000 you@your-vps

Em seguida, abra http://127.0.0.1:3000 na sua própria máquina. O tráfego passa pela sessão SSH existente, e nada de novo fica a escutar na internet pública. Nem todos os agentes precisam sequer de uma porta: as sessões do Claude Code no mesmo VPS comunicam entre si através do terminal, pelo que a única coisa exposta é o próprio SSH. O mesmo procedimento de usar loopback e um túnel aplica-se a todos os painéis de agentes que alojar; aceder à interface de análise do open-kritt através de um túnel funciona da mesma forma, mas na porta 5173. Para uma configuração mais permanente, coloque-o atrás de uma VPN. Em qualquer dos casos, coloque uma firewall com política deny por omissão à frente do servidor, para que nada fique exposto por acidente. Lembre-se também de que uma firewall que cubra apenas IPv4 deixa a mesma porta aberta em IPv6. Essa é a lacuna na firewall IPv6 que apanha tantas pessoas.

Isole a chave do modelo e quaisquer credenciais do repositório

O OpenHands precisa de uma chave de API para o seu modelo e, muitas vezes, de um token para clonar e enviar alterações para os seus repositórios. Ambos podem gastar dinheiro e agir em seu nome, por isso trate-os como palavras-passe. Mantenha-os num ficheiro de ambiente que apenas a conta correta possa ler. Nunca os inclua no comando de execução, onde ficam no histórico da shell e na lista de processos. Nunca os guarde num ficheiro dentro de um repositório git. Se mantiver os originais num gestor de palavras-passe autoalojado, reforce também a segurança desse servidor, porque os pontos fracos de um cofre são o seu token de administrador e o ficheiro de cópia de segurança, e não os itens encriptados em si, como explica a verificação do reforço de segurança do Vaultwarden.

Execute-o num servidor descartável

Como o controlador precisa de acesso ao socket do Docker, não é possível isolar totalmente o OpenHands do sistema anfitrião. A mitigação correta é isolá-lo por colocação: execute o OpenHands num VPS dedicado que não contenha mais nada importante, e não no servidor que também executa a sua base de dados ou o seu site. Crie um snapshot antes de começar e reconstrua o servidor a partir desse snapshot, em vez de confiar num servidor que executou código escrito pelo agente durante uma semana. Um VPS barato, descartável e dedicado a uma única finalidade é o local adequado para o executar. A colocação é a única opção de controlo que o OpenHands oferece neste caso. Se também quiser controlar o que o agente pode fazer antes de parar para pedir confirmação, os modos de permissão do Claude Code mostram como funciona esse segundo mecanismo num servidor que ninguém está a monitorizar.

Reforce a segurança do servidor

O restante corresponde à higiene normal de um servidor, mas é ainda mais importante neste caso porque a carga de trabalho apresenta mais riscos do que o habitual. Crie um utilizador administrativo sem privilégios em vez de trabalhar como root, seguindo executar serviços como um utilizador sem privilégios. Configure o SSH para usar apenas autenticação por chave. Em seguida, execute a lista de verificação abaixo e guarde-a num local que volte a consultar.

Para compreender os componentes envolvidos em vez de apenas os executar, consulte criar o seu próprio agente de IA numa VPS; para uma plataforma com menos código, alojar o Dify por conta própria oferece uma introdução mais simples.

FAQ

O OpenHands é seguro para executar num servidor?

Pode ser, se forem tomadas precauções, mas é mais arriscado do que uma aplicação Web comum porque escreve e executa código, e o seu controlador tem acesso ao socket Docker do host, o que equivale efetivamente a root na máquina. Execute-o numa VPS dedicada e descartável, sem outros dados valiosos, mantenha a sua interface Web em loopback, acessível através de um túnel SSH ou de uma VPN, isole as suas chaves e reforce a segurança do sistema. Não o execute junto dos seus serviços importantes.

Porque é que o OpenHands precisa do socket Docker?

O OpenHands executa cada tarefa num contentor sandbox novo e pede ao daemon Docker do host para criar esses contentores, montando /var/run/docker.sock no seu controlador. Isto dá ao contentor do controlador controlo sobre o Docker no host, o que é poderoso e arriscado. Por isso, o próprio host deve ser tratado como um sistema que executa código não confiável.

O OpenHands pode usar um modelo local em vez de uma API paga?

Sim. O OpenHands suporta modelos locais servidos pelo Ollama ou pelo vLLM. Assim, pode executá-lo totalmente no seu próprio ambiente, sem custo por token e sem que os dados saiam do servidor. Precisa de uma máquina com memória suficiente para um modelo de programação capaz. Esta é a mesma questão de dimensionamento abordada no guia do Ollama.

Devo executar o OpenHands no meu servidor principal?

Não. Como executa código criado por um agente e tem acesso ao socket Docker, mantenha-o numa VPS separada e dedicada, que esteja disposto a reinstalar. Colocá-lo no mesmo sistema que uma base de dados, um site ou os seus outros serviços significa que um erro do agente, ou um bug no próprio OpenHands, pode alcançar recursos que nunca deveria conseguir utilizar.