Como hospedar o Agentlas OS em um VPS

O que o Agentlas OS realmente é

O Agentlas OS é um runtime de agentes de código aberto que mantém agentes especializados no disco como pacotes e monta um orquestrador temporário para cada tarefa. A instalação é feita na sua própria conta de utilizador num VPS Linux. Não é um serviço. Não existe nenhum daemon, nenhuma porta em escuta, nenhuma interface web nem nenhuma imagem de contentor no repositório.

A última frase determina todo o resto desta página. A maioria dos sistemas multiagente executa um processo supervisor que permanece ativo e mantém os agentes. O Agentlas inverte esse modelo: os especialistas são ficheiros armazenados no disco, e o orquestrador só existe enquanto uma tarefa está em execução. Na prática, um hub inativo consome espaço em disco, não memória.

O projeto chama ao seu núcleo aberto Hephaestus, e é esse nome que verá nos comandos, caminhos e variáveis de ambiente. O repositório é agentlas-ai/Agentlas-OS, está licenciado sob Apache-2.0 e foi escrito principalmente em Python.

Qual é, na realidade, o grau de maturidade deste projeto

O repositório foi criado em 4 June 2026. Em 12 August 2026, tinha cerca de dez semanas, aproximadamente 1,150 stars e 112 forks. Isto é recente para algo que será usado em trabalho real.

A cadência de releases é mais importante do que a idade. A versão v1.1.103 foi publicada em 8 August 2026, e a v1.2.0 foi disponibilizada em 12 August 2026. Isso corresponde a mais de uma centena de releases identificadas na série 1.1, com várias publicadas em alguns dias e geradas por automação. Um projeto que evolui a esse ritmo pode alterar o comportamento entre uma terça-feira e uma quinta-feira.

Por isso, fixe a release. O instalador lê uma variável de ambiente para esse efeito, e todo o guia abaixo utiliza essa variável. Uma instalação sem uma versão fixa de um projeto que lança várias releases por dia fornece-lhe o que estiver disponível em main nesse momento.

O que é necessário no VPS

Os requisitos são reduzidos porque nada é executado em segundo plano.

• Um VPS Linux. Ubuntu 24.04 é uma boa base. O instalador deteta o sistema operativo com uname -s e segue um ramo não macOS para Linux, portanto é compatível com um servidor sem interface gráfica.
• curl, tar e git no servidor, além de um interpretador Python funcional.
• Acesso HTTPS de saída a raw.githubusercontent.com e github.com. O instalador descarrega um arquivo de release e verifica o respetivo SHA-256, portanto um servidor sem conectividade de saída não consegue concluir a instalação.
• Um host harness, que é o agente de programação que comunica efetivamente com um modelo. Claude Code, Codex, opencode, goose e Hermes são todos adapters suportados.

Não é necessário ter root. O instalador escreve apenas no seu diretório pessoal e em ~/.local/bin. Emite um aviso, em vez de abortar, quando um caminho não permite escrita. Se ainda estiver a escolher o próprio servidor, executar um agente de programação num VPS aborda a imagem base e a configuração de acesso sobre as quais esta instalação assenta.

Instale a versão fixada

O README upstream documenta uma única linha que encaminha um script de main diretamente para bash. Transfira-o e leia-o primeiro. O script escreve na configuração da shell e em todos os harnesses de agentes que encontrar, por isso vale a pena dedicar-lhe dez segundos de atenção.

curl -fsSL -o install-all-runtimes.sh \
  https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh
less install-all-runtimes.sh
HEPHAESTUS_REF=v1.2.0 bash install-all-runtimes.sh

HEPHAESTUS_REF é o pin. Dentro do script, a linha é version="${HEPHAESTUS_REF:-v1.2.0}", por isso deixá-lo indefinido faz com que hoje obtenha v1.2.0 e na próxima semana obtenha outra versão. Defina-o explicitamente para que a reconstrução em outubro instale o que testou em agosto.

Há uma limitação importante: o URL do script acima acompanha main, enquanto HEPHAESTUS_REF fixa o payload de runtime que o script transfere. São duas coisas diferentes. Para fixar ambas, obtenha o script a partir da tag em vez de main, substituindo main por v1.2.0 nesse URL.

Uma execução bem-sucedida mostra os caminhos onde escreveu dados, incluindo estas duas linhas:

Installed runner: /home/you/.agentlas/runtime/current/bin/hephaestus
Installed shell commands in /home/you/.local/bin (add ~/.local/bin to PATH to use them)

Essa segunda linha é frequentemente ignorada. Numa instalação nova do Ubuntu, ~/.local/bin está muitas vezes ausente de PATH, por isso todos os comandos hep-* falham com command not found, embora a instalação tenha sido concluída. Corrija o problema e confirme:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
hep-global status

hep-global status indica o que o router global instalou e quais harnesses detetou. Se for executado, o seu PATH está correto.

Onde o estado fica

Tudo é um ficheiro dentro do seu diretório pessoal, o que simplifica as cópias de segurança e a migração.

• ~/.agentlas/runtime/v1.2.0/ contém o runtime, com ~/.agentlas/runtime/current/ como symlink para a versão ativa. É possível manter duas versões fixadas lado a lado.
• ~/.local/bin/ contém os wrappers da shell: hephaestus, hep-build, hep-network, hep-search, hep-storm, hep-cloud e hep-upload.
• ~/.agentlas/networking/memory/ contém a memória persistente: playbook-registry.json, playbook-candidates.jsonl e memory-events.jsonl.
• ~/.agentlas/networking/hub-agents/<slug>/memory/experience.sqlite contém a experiência específica de cada agente, associada ao respetivo proprietário.
• <project>/.agentlas/ontology-runtime.sqlite contém o estado específico de cada projeto, para que este acompanhe o repositório e não o servidor.
• ~/.cache/agentlas/python contém a cache do Python no Linux. O macOS utiliza um caminho diferente; o instalador seleciona essa variante com uname.

A documentação da memória afirma explicitamente que segredos, credenciais em bruto e transcrições completas não devem ser guardados em nenhum âmbito de memória. Os valores das credenciais permanecem em ficheiros locais ignorados pelo git, e os registos de memória contêm apenas nomes e caminhos. Faça cópias de segurança de ~/.agentlas e dos diretórios .agentlas dos seus projetos para poder reconstruir o ambiente num novo VPS.

Para quais backends de modelos pode encaminhar

Este é o detalhe que reformula toda a configuração: o Agentlas não chama uma API de modelo. O harness do host faz isso.

O documento de arquitetura descreve adaptadores de runtime que traduzem um core para cada harness e afirma que o runtime do host gere as credenciais do modelo. O Agentlas fornece duas interfaces que um harness utiliza: um ficheiro AgentSkills e um servidor MCP (model context protocol) que comunica através de stdio. Portanto, a pergunta "quais modelos o Agentlas suporta" significa, na realidade, "quais modelos o seu harness suporta", e a resposta é qualquer modelo a que Claude Code, Codex, opencode, goose ou Hermes consiga aceder.

O registo do servidor MCP tem este aspeto numa configuração TOML ao estilo do Codex:

[mcp_servers.hephaestus-network]
command = "~/.agentlas/runtime/current/bin/hephaestus"
args = ["mcp", "serve"]

O mesmo servidor é registado automaticamente em ~/.cursor/mcp.json, ~/.config/goose/config.yaml e nas restantes configurações dos harnesses durante a instalação. Se estiver a configurar vários destes serviços no mesmo sistema, executar servidores MCP numa VPS explica com mais detalhe o modelo de stdio e de processos.

Aponte para um endpoint Ollama auto-hospedado

Como o harness controla a ligação ao modelo, apontar o Agentlas para modelos locais significa apontar o harness para o Ollama. O Ollama adicionou um subcomando launch na v0.15 especificamente para este fim, e ele continua disponível na v0.32.9 em 11 August 2026. Este subcomando configura um harness existente para utilizar modelos locais sem definir variáveis de ambiente:

ollama pull qwen3-coder:30b
ollama launch opencode

Substitua opencode por claude, codex ou droid, consoante o harness instalado. Em seguida, encaminhe um pedido pelo runtime local:

~/.agentlas/runtime/current/bin/hephaestus route "summarise the failing tests" --runtime ollama

Um encaminhamento bem-sucedido devolve uma decisão JSON que identifica o agente ou a equipa selecionada, com um receipt_id. Se não devolver nada útil, a causa habitual é o comprimento do contexto. A documentação do Agentlas recomenda um modelo com pelo menos 64k de contexto para sessões com muito encaminhamento e indica qwen3-coder, gemma3 e deepseek-r1 como exemplos. As próprias orientações do Ollama para ferramentas de programação definem o mesmo mínimo de 64k. As decisões de encaminhamento incluem o inventário de agentes no prompt. Por isso, um modelo com contexto de 8k ou 32k trunca o inventário e faz más escolhas.

Existe uma limitação que o slogan não menciona. Ollama, Gemma e DeepSeek não têm um sistema próprio de plugins ou comandos. Por isso, os comandos slash /agentlas não existem nesses modelos. Numa configuração com modelos locais, o sistema é controlado através do servidor MCP e do comando hephaestus route. Isto reduz efetivamente a superfície disponível. É o compromisso necessário para manter os pesos no seu próprio servidor.

O custo de um hub de especialistas inativos na RAM

Nada. Essa é toda a resposta, e pode comprová-la em vez de confiar nela.

Os especialistas do hub carregados chegam como artefactos de pacotes, não como processos. Um especialista é um agent.md e um diretório .agentlas/ com JSON: routing-card.json para acionadores e capacidades, memory-map.json para limites de escrita e mode-map.json para indicar se é executado sozinho ou em equipa. A Hephaestus Network é descrita como um agendador em processo, sem serviço em segundo plano. Entre tarefas, confirme por si:

pgrep -af hephaestus
systemctl --user list-units --type=service | grep -i agentlas
du -sh ~/.agentlas

Os dois primeiros comandos não mostram nada num sistema inativo, porque não há nada residente. O terceiro mostra o único custo imposto por um hub parado: espaço em disco. Esse custo aumenta com o número de especialistas mantidos e com o modelo de embeddings incluído na release do runtime.

Por isso, a questão da memória é totalmente uma questão do pico de utilização. Esse pico corresponde ao seu harness e ao backend do modelo. Se o harness comunicar com uma API alojada, o custo residente é um processo com algumas centenas de megabytes. Se alojar os pesos localmente, os pesos são o custo principal:

[
  {
    "label": "Hosted API model",
    "weights_gb": 0
  },
  {
    "label": "gemma3:4b",
    "weights_gb": 3.3
  },
  {
    "label": "gemma3:12b",
    "weights_gb": 8.1
  },
  {
    "label": "gemma3:27b",
    "weights_gb": 17
  },
  {
    "label": "qwen3-coder:30b",
    "weights_gb": 19
  }
]

Estes são os tamanhos de download publicados na biblioteca de modelos do Ollama, não medições de uma execução de benchmark. A cache KV para um contexto de 64k é adicionada a todos os valores acima de zero. O modelo que a documentação do Agentlas apresenta primeiro, qwen3-coder:30b, precisa de 19 GB de pesos antes do contexto. Até a variante Gemma 27B requer 17 GB. Perante esses valores, a própria camada Agentlas não aparece no orçamento.

Como isto se compara com executar um único harness

Execute um harness contra uma API alojada e o seu VPS terá um processo. Adicione o Agentlas e terá o mesmo processo, mais ficheiros. O orquestrador não é um programa adicional de longa duração. É um prompt maior, montado a partir dos pacotes no disco e depois descartado.

O custo que aumenta é o contexto, não a memória. Um orquestrador que inclui vários cartões de especialistas e os respetivos metadados de encaminhamento consome mais tokens por tarefa do que um harness simples. Numa API alojada, isso representa um custo financeiro, não RAM. Com pesos locais, representa tempo, porque um prompt mais longo implica um prefill mais demorado no CPU ou uma GPU mais ocupada.

Por isso, as recomendações de dimensionamento para uma máquina deste tipo dependem da escolha do modelo, não do framework de agentes. Dimensionar RAM e CPU para um VPS com agente de programação explica isto em detalhe, e a conclusão mantém-se aqui: escolha o plano para o backend que pretende executar e acrescente alguns gigabytes de margem para o harness. Se quiser comparar com o modelo de supervisor sempre ativo, o harness multiagente Omnigent mantém o coordenador residente. É a opção oposta e o efeito aparece diretamente na memória em estado ocioso.

Modos de falha e as mensagens que verá

hep-build: command not found logo após uma instalação limpa. O instalador escreveu em ~/.local/bin, que não está em PATH numa imagem Ubuntu predefinida. Isso foi indicado na última linha, mas a linha passou rapidamente. Adicione a exportação apresentada acima.

O comportamento muda depois de reconstruir o servidor. Não definiu HEPHAESTUS_REF, por isso o instalador usou a tag que estava atual nesse dia. Fixe-a e registe essa versão junto dos restantes números de versão.

O encaminhamento escolhe o especialista errado num modelo local. A janela de contexto do modelo é demasiado pequena para o inventário de agentes. Mude para um modelo com 64k ou mais e defina o comprimento de contexto do Ollama para o mesmo valor, porque o valor predefinido é inferior ao necessário pelas ferramentas de programação.

ollama launch não é reconhecido. Este subcomando foi introduzido no Ollama v0.15. Os pacotes mais antigos de um repositório de distribuição são anteriores a essa versão, por isso instale uma versão atual do Ollama.

A instalação escreve em harnesses que não esperava. O script deteta e configura todos os harnesses encontrados, escrevendo em ~/.claude/, ~/.codex/, ~/.gemini/, ~/.cursor/ e noutros diretórios. Num servidor de compilação partilhado, leia o script antes de o executar e confirme quais desses diretórios são relevantes.

Executar isto agora

Um projeto com dez semanas de existência e releases automáticos várias vezes por dia não deve ser usado numa carga de produção. A arquitetura é genuinamente interessante, a licença é Apache-2.0 e o design baseado em ficheiros significa que a desinstalação consiste em eliminar dois diretórios. Estes factos tornam barato experimentar e caro depender dele.

Uma abordagem sensata por agora: fixe a versão v1.2.0, execute-o numa máquina que possa reconstruir, mantenha ~/.agentlas nas suas cópias de segurança e volte a ler o changelog antes de alterar a versão fixada. Para uma análise mais ampla do que existe neste espaço e do grau de maturidade de cada opção, a análise de agentes de IA self-hosted é o melhor ponto de partida, e alojar um agente Hermes num VPS aborda uma das harnesses às quais o Agentlas se adapta.

FAQ

O Agentlas OS é executado como um servidor na minha VPS?

Não. Não existe daemon, porta em escuta nem imagem de contentor no repositório. O instalador grava um runtime em ~/.agentlas/runtime/ e wrappers de comandos em ~/.local/bin, e a Hephaestus Network é um agendador no processo, não um serviço em segundo plano. Pode confirmar isto numa máquina inativa: pgrep -af hephaestus não apresenta qualquer saída e não existe nenhuma unidade systemd para ativar. A auto-hospedagem significa que o código e o estado estão na sua máquina, não que exista um serviço em escuta.

Quanta RAM utiliza um hub de especialistas inativos?

Nenhuma, porque os especialistas inativos não são processos. Um especialista é um ficheiro agent.md e um diretório .agentlas/ que contém routing-card.json, memory-map.json e metadados semelhantes, por isso um hub parado ocupa espaço em disco. Meça-o com du -sh ~/.agentlas. A memória só é consumida enquanto uma tarefa é executada, e quem a consome é o processo do seu harness e o backend do seu modelo, não a camada Agentlas.

Que modelos posso usar e posso apontá-lo para o meu próprio Ollama?

O Agentlas não chama APIs de modelos diretamente. O harness anfitrião gere as credenciais e a ligação, por isso os modelos suportados são os que o seu harness suporta. Para pesos locais, execute ollama launch opencode, substituindo claude, codex ou droid. Isto configura o harness para utilizar o seu servidor Ollama sem variáveis de ambiente. Use um modelo com um contexto de pelo menos 64k, como qwen3-coder ou gemma3, porque os prompts de encaminhamento incluem o inventário de agentes e são truncados de forma significativa em janelas menores.

Que versão devo instalar e por que motivo o pinning é importante neste caso?

Instale a v1.2.0, a release etiquetada atual em 12 August 2026, definindo HEPHAESTUS_REF=v1.2.0 antes de executar o instalador. O valor predefinido do próprio script é version="${HEPHAESTUS_REF:-v1.2.0}", que acompanha a próxima etiqueta criada pelos mantenedores. O pinning é mais importante do que o habitual porque o projeto publicou mais de uma centena de releases na série 1.1, várias em alguns dias. Por isso, uma nova compilação sem versão fixada, feita semanas depois, não lhe fornecerá o sistema que testou.