Como instalar OpenHands em um VPS com Docker

O que é o OpenHands, e o único risco que você deve entender primeiro

O OpenHands, anteriormente OpenDevin, é um agente autônomo de engenharia de software. Você fornece uma tarefa em linguagem natural e ele planeja o trabalho, escreve código, executa comandos, lê a saída e itera até concluir a tarefa. Você o executa em seu próprio servidor com Docker e o aponta para um modelo de linguagem. Em um VPS, ele se torna um agente de codificação que trabalha enquanto você está ausente.

Um fato deve orientar toda a sua configuração. O OpenHands não apenas sugere código, ele o executa. Para isso, o container do controller monta o Docker socket do host em /var/run/docker.sock para poder criar containers sandbox para cada tarefa. Qualquer coisa que consiga se comunicar com o Docker socket pode iniciar um novo container que monte todo o sistema de arquivos do host, o que significa que o acesso ao socket é efetivamente root na máquina. Portanto, trate o servidor do OpenHands como um servidor que executa código não confiável, pois é exatamente isso que ele faz. Todas as escolhas de hardening abaixo derivam disso.

O que você precisa

Você precisa de um VPS rodando Ubuntu 24.04 com um Docker Engine recente, pelo menos 4 GB de RAM e uma chave de API para um modelo de linguagem (OpenAI, Anthropic ou Google), ou um modelo local servido pelo Ollama no mesmo VPS. O OpenHands suporta dezenas de backends de modelos, portanto a escolha é sua. Se você nunca configurou containers antes, os conceitos básicos de Docker em um VPS cobrem o que este guia assume.

Instalação com Docker

O OpenHands é distribuído em duas imagens: a imagem da aplicação que você executa e a imagem do agent-server que ele baixa para rodar o sandbox de cada tarefa. Execute desta forma, substituindo as tags atuais das documentações 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 economizam uma hora de confusão. A imagem da app e a imagem do agent-server possuem números de versão diferentes propositalmente; não tente igualá-las: use a tag do agent-server que a documentação pareia com sua versão da app. E observe o -p 127.0.0.1:3000:3000 em vez de -p 3000:3000. Essa única mudança é a diferença entre uma Web UI que apenas você pode acessar e uma que toda a internet pode acessar, que é o assunto da próxima seção.

Mantenha a Web UI fora da internet pública

O OpenHands serve sua interface na porta 3000. Essa interface controla um agente que executa código; portanto, publicá-la na internet dá a qualquer pessoa que a encontre um caminho remoto para um processo que executa comandos. Vincule-a ao loopback, como o comando de execução acima faz, e acesse-a do seu laptop via túnel SSH:

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

Em seguida, abra http://127.0.0.1:3000 em sua própria máquina. O tráfego utiliza sua sessão SSH existente e nada novo fica ouvindo na internet pública. Para uma configuração mais permanente, use uma VPN em vez disso. De qualquer forma, coloque um firewall de "deny-by-default" na frente do servidor para que nada seja exposto por acidente, e lembre-se que um firewall que cobre apenas IPv4 deixa a mesma porta aberta no IPv6, que é a brecha de firewall IPv6 que afeta tantas pessoas.

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

O OpenHands precisa de uma chave de API para seu modelo e, frequentemente, de um token para clonar e fazer push em seus repositórios. Ambos podem gastar dinheiro e agir como você, então trate-os como senhas. Mantenha-os em um arquivo de ambiente que apenas a conta correta possa ler; nunca os coloque no comando de execução, onde eles ficam registrados no histórico do shell e na lista de processos, e nunca em um arquivo dentro de um repositório git.

Execute em uma máquina descartável

Como o controller deve conter o Docker socket, você não pode isolar completamente o OpenHands do host. A mitigação real é o isolamento por posicionamento: execute o OpenHands em um VPS dedicado que não contenha nada mais que seja importante para você, não no servidor que também roda seu banco de dados ou seu site. Tire um snapshot antes de começar e reconstrua a partir desse snapshot em vez de confiar em uma máquina que executou código gerado por um agente por uma semana. Um VPS barato, descartável e de propósito único é o ambiente ideal para ele.

Reforce o servidor ao redor dele

O restante é higiene padrão de servidor, e isso importa mais aqui do que o normal, pois a carga de trabalho é mais arriscada do que o normal. Crie um usuário administrador sem privilégios em vez de trabalhar como root, seguindo a execução de serviços como um usuário sem privilégios. Mude o SSH para autenticação apenas por chave. Em seguida, execute o checklist abaixo e guarde-o em um lugar onde você o verá novamente.

Para entender as partes móveis em vez de apenas executá-las, veja construindo seu próprio agente de IA em um VPS; para uma plataforma de baixo código, self-hosting Dify é uma alternativa mais simples.

FAQ

É seguro rodar o OpenHands em um servidor?

Pode ser, com cuidado, mas é mais arriscado do que um app web comum porque ele escreve e executa código, e seu controller possui o Docker socket do host, que é efetivamente root na máquina. Execute-o em um VPS dedicado e descartável que não contenha nada de valor, mantenha sua Web UI no loopback atrás de um túnel SSH ou VPN, isole suas chaves e reforce o servidor. Não o execute ao lado de seus serviços importantes.

Por que o OpenHands precisa do Docker socket?

O OpenHands executa cada tarefa em um container sandbox novo e solicita ao daemon do Docker do host que crie esses containers montando o /var/run/docker.sock dentro de seu controller. Isso dá ao container do controller o controle sobre o Docker no host, o que é poderoso e arriscado; portanto, o próprio host deve ser tratado como um 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 vLLM, então você pode executá-lo totalmente de forma self-hosted, sem custo por token e sem que os dados saiam do seu servidor. Você precisa de uma máquina com memória suficiente para um modelo de codificação capaz, que é a mesma questão de dimensionamento abordada no guia do Ollama.

Devo rodar o OpenHands no meu servidor principal?

Não. Como ele executa código gerado por agentes e possui o Docker socket, mantenha-o em um VPS separado e de propósito único que você esteja disposto a reconstruir. Co-localizá-lo com um banco de dados, um site ou seus outros serviços significa que um erro do agente, ou um bug nele, pode alcançar recursos que ele nunca deveria tocar.