Como configurar o Hermes Workspace

O Hermes Workspace é uma interface web de código aberto para o Hermes Agent, um agente de IA que se aprimora sozinho, desenvolvido pela Nous Research.

Ele reúne o chat do agente, a memória persistente, o mercado de habilidades, o terminal e a orquestração multiagente em um único painel auto-hospedado, que você pode acessar de qualquer dispositivo.

Para configurar o Hermes Workspace em um servidor virtual privado (VPS), faça a instalação do Workspace junto com o agente, configure o gateway e o painel e acesse a interface por meio de um túnel SSH ou de um domínio.

Executar o Hermes Workspace em um VPS mantém suas conversas, a memória do agente e as chaves de API na infraestrutura que você controla, em vez de depender de serviços de terceiros.

1. Verifique os pré-requisitos

O Hermes Workspace roda em um VPS com pelo menos 2 GB de RAM e uma das principais distribuições Linux, como o Ubuntu 24.04. O Workspace funciona como interface, enquanto o Hermes Agent cuida das tarefas em segundo plano.

Configure um VPS primeiro, se ainda não tiver um, e depois conecte-se a ele via SSH.

O Hermes Workspace precisa de três ferramentas: Node.js 22 ou superior, Python 3.11 ou superior e pnpm. O Ubuntu 24.04 já vem com uma versão compatível do Python, então você só precisa realizar a instalação do Node.js e do pnpm.

Primeiro, atualize o sistema:

sudo apt update

Realize a instalação do curl e do git e, em seguida, adicione o repositório NodeSource para o Node.js 22:

sudo apt install -y curl git
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Realize a instalação do pnpm usando o npm:

sudo npm install -g pnpm

Verifique se cada ferramenta está instalada e se está na versão necessária antes de continuar:

node -v # 22.x or higher
python3 -V # 3.11 or higher
pnpm -v

2. Instale o Hermes Workspace

Se você nunca instalou o Hermes Agent antes, configure o Hermes Workspace com o instalador oficial de uma linha. Ele clona o workspace, instala o Hermes Agent pelo PyPI e cria os arquivos iniciais .env com um único comando:

curl -fsSL https://raw.githubusercontent.com/outsourc-e/hermes-workspace/main/install.sh | bash

Na primeira execução, o instalador pede que você escolha um provedor de modelo e insira uma chave de API, então tenha uma chave disponível. Quando terminar, você verá uma mensagem de confirmação indicando que a instalação foi bem-sucedida.

Se você já instalou o Hermes Agent, pule o instalador de uma linha. Em vez disso, clone o repositório do Hermes Workspace separadamente e configure-o para os seus serviços existentes:

git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace
pnpm install
cp .env.example .env
echo 'HERMES_API_URL=http://127.0.0.1:8642' >> .env
echo 'HERMES_DASHBOARD_URL=http://127.0.0.1:9119' >> .env

Use 127.0.0.1 se o agente estiver rodando no mesmo servidor. Use o endereço IP real do servidor se ele estiver rodando em outro lugar. De qualquer forma, você ainda vai precisar definir a chave do gateway em seguida.

Independentemente do seu método de instalação, o workspace e o gateway precisam compartilhar a mesma chave secreta. Isso requer três novas entradas em dois arquivos.

Primeiro, gere a chave secreta e copie-a em um lugar seguro:

openssl rand -hex 32

Abra o arquivo de ambiente do agente com o editor de texto nano:

nano ~/.hermes/.env

Adicione essas duas linhas ao arquivo. Substitua seu-gateway-secret pela chave secreta que você gerou antes:

API_SERVER_ENABLED=true
API_SERVER_KEY=your-gateway-secret

A variável API_SERVER_ENABLED ativa a API HTTP usada pelo Workspace, e API_SERVER_KEY protege a API com uma chave secreta.

O gateway precisa dessas duas configurações para disponibilizar a API, mesmo quando o espaço de trabalho e o gateway rodam no mesmo servidor. É fácil deixar essa etapa de lado, porque, em uma configuração apenas local, pode parecer que não precisa de senha.

Salve o arquivo e feche o nano com Ctrl+X → Y → Enter.

Agora, abra o arquivo de ambiente do espaço de trabalho:

nano ~/hermes-workspace/.env

Adicione o token usando a mesma chave secreta, para que API_SERVER_KEY e HERMES_API_TOKEN tenham o mesmo valor:

HERMES_API_TOKEN=your-gateway-secret

Salve o arquivo da mesma forma para concluir a configuração.

3. Inicie o gateway e o workspace

Três serviços do Hermes são executados juntos: o gateway na porta 8642, o painel na porta 9119 e a interface do workspace na porta 3000. O gateway e o painel fazem parte do Hermes Agent, enquanto a interface é a parte que você usa no navegador.

Vá até a pasta do workspace:

cd ~/hermes-workspace

Inicie o gateway, o painel e a interface do workspace com um único comando:

npx concurrently --names "gateway,dashboard,workspace" --prefix-colors "blue,green,yellow" "hermes gateway run" "hermes dashboard" "pnpm dev"

A saída exibe o URL da interface do workspace no IP do seu VPS, na porta 3000, como, por exemplo, http://22.222.222.84:3000. Abra esse endereço no navegador.

O painel carrega pronto para uso, então você pode começar a conversar, acessar a memória e explorar as habilidades ou abrir o terminal integrado na hora.

Se você fechar a sessão SSH ou perder a conexão, esses processos também são encerrados. Para mantê-los em execução mesmo depois que o SSH se desconectar, execute-os dentro de uma sessão do tmux:

tmux new -s hermes
cd ~/hermes-workspace
npx concurrently "hermes gateway run" "hermes dashboard" "pnpm dev"

Desconecte com Ctrl+B e, em seguida, D. Reconecte mais tarde com tmux attach -t hermes.

Para confirmar se o gateway e o painel de controle estão respondendo, abra uma nova janela de terminal e execute estas duas verificações:

curl http://127.0.0.1:8642/health
curl http://127.0.0.1:9119/api/status

O primeiro comando verifica o gateway, que retorna {“status”:”ok”,”platform”:”hermes-agent”}.

O segundo comando verifica o painel. Os campos importantes são “gateway_running”:true e o estado do api_server como “connected”, o que confirma que o gateway está funcionando e que seu servidor de API está conectado.

Você também precisa verificar o modo de execução no terminal que está rodando os serviços. Uma linha no log do workspace que inclua mode=zero-fork indica que o gateway e o painel foram emparelhados.

Como configurar o Hermes Workspace na Hostinger

Na Hostinger, o Hermes Workspace está disponível como um template Docker com instalação em um clique que configura automaticamente os contêineres do agente e do workspace.

Isso evita que você precise executar comandos de instalação e configuração manualmente, o que pode causar erros.

Se você é um cliente novo, abra a página do template do Hermes Workspace e escolha seu plano, período de cobrança e localização do servidor. Depois de concluir a compra, insira uma senha para o espaço de trabalho e uma chave de API.

A instalação leva cerca de cinco minutos. Quando terminar, o sistema te redireciona para a página do Gerenciador Docker. Lá, clica em Abrir na coluna Acesso para entrar na interface web.

Se você já tem um VPS da Hostinger, também pode instalar o template Hermes Workspace pelo hPanel.

1. Vá para hPanel → VPS → Gerenciar → SO e Painel → Sistema Operacional.
2. Na seção Alterar SO, procure por Hermes Workspace e selecione-o.

3. Insira uma senha para o workspace e uma chave de API do seu provedor preferido.
4. Clique em Próximo → Implantar.

Quando a implantação terminar, vá até Gerenciador Docker → Projetos e clique em Abrir para acessar a interface web do espaço de trabalho.

Erros comuns na configuração do Hermes Workspace

A maioria dos erros de configuração do Hermes Workspace tem causas recorrentes, como API desativada, chave do gateway ausente, painel não iniciado ou versão desatualizada do agente.

• A API HTTP do gateway está desativada. O erro “Não foi possível acessar o gateway do Hermes nas portas 8645, 8642 ou 8643” significa que o workspace não consegue acessar a API HTTP do gateway. Isso acontece quando o gateway está rodando, mas funcionando apenas com plataformas de mensagens, com a API HTTP desativada. Adicione API_SERVER_ENABLED=true ao ~/.hermes/.env e, em seguida, reinicie o gateway com pkill -f “hermes gateway” e hermes gateway run.
• Chave do servidor de API ausente. O erro “API_SERVER_KEY é obrigatória para o servidor de API, incluindo ligações apenas para loopback em 127.0.0.1” significa que o gateway se recusa a iniciar sua API HTTP. Isso acontece quando API_SERVER_KEY não está definida, já que o gateway exige essa chave inclusive em uma configuração local. Gere uma com openssl rand -hex 32, adicione-a como API_SERVER_KEY no arquivo ~/.hermes/.env e defina o mesmo valor como HERMES_API_TOKEN no arquivo ~/hermes-workspace/.env.
• O painel não está funcionando. A linha de log “mode=portable with missing=[…dashboard]” significa que o workspace voltou para o modo portátil, onde sessões, habilidades, memória e tarefas não estão disponíveis. Isso acontece quando o painel não está rodando na porta 9119, geralmente porque o comando de inicialização pulou essa etapa. Pare os serviços em execução com Ctrl+C e, depois, inicie os três juntos com npx concurrently para que o Workspace seja iniciado com o painel e saia do modo portátil.
• A lista de permissões de mensagens não está definida. O aviso “Nenhuma lista de permissões de usuários configurada” significa que o agente bloqueia mensagens de usuários em qualquer plataforma conectada. Isso acontece quando uma plataforma de mensagens como o Telegram ou o Discord é ativada sem uma lista de usuários permitidos. Adicione GATEWAY_ALLOW_ALL_USERS=true ao arquivo ~/.hermes/.env para permitir o acesso de todos os usuários, ou defina listas de permissões por plataforma para limitar quem pode acessá-la.
• O Hermes Agent está desatualizado. A linha de log “missing=[chatCompletions, models, streaming, …]” significa que o workspace não consegue encontrar os endpoints esperados, mesmo que o gateway responda. Isso acontece quando o Hermes Agent instalado é mais antigo que o espaço de trabalho, então o agente não disponibiliza esses endpoints. Para uma instalação via git, atualize o agente com cd ~/hermes-agent && git pull && uv pip install -e . Para uma instalação via PyPI, execute um pip upgrade. Depois, reinicie o gateway com hermes gateway run.

Quanto tempo leva para configurar o Hermes Workspace?

A configuração do Hermes Workspace leva cerca de 15 a 30 minutos do início ao fim, dependendo se você está fazendo uma instalação nova ou se já configurou o Hermes Agent antes.

A instalação do Node.js e do pnpm leva menos de cinco minutos. O instalador de uma linha, então, baixa o workspace e o agente em cerca de cinco minutos.

Se você nunca configurou o Hermes Agent antes, essa costuma ser a parte que demora mais. Leva cerca de 10 minutos, porque você precisa escolher um provedor, colar uma chave de API e confirmar as configurações.

Se você já instalou o Hermes Agent e só precisa clonar o Workspace no seu ambiente atual, o processo deve levar cerca de cinco minutos.

Editar os arquivos de ambiente leva mais dois ou três minutos, e iniciar os serviços leva mais um ou dois minutos.

Posso executar várias instâncias do Hermes Workspace na mesma máquina?

Sim, você pode rodar mais de uma instância do Hermes Workspace na mesma máquina. Cada instância é uma cópia separada, então precisa de seu próprio gateway, painel e interface de usuário.

O problema é que dois serviços não podem compartilhar uma porta. Apenas um gateway pode usar a porta 8642. Por isso, atribua uma porta diferente ao gateway da segunda instância e aponte seu HERMES_API_URL para essa porta.

Faça o mesmo com a interface de usuário, executando-a em uma porta livre com PORT=3001 pnpm dev. Cada instância também mantém sua própria configuração, então elas não vão substituir os arquivos umas das outras.

Se você quiser apenas executar agentes diferentes em uma única instância do workspace, não precisa de uma segunda instância. Adicione cada um como um perfil em ~/.hermes/profiles/nome-do-perfil, onde nome-do-perfil é um nome que você escolher. Depois, você pode alternar entre os perfis pela interface do usuário na web.

Próximos passos após configurar o Hermes Workspace

Com o Hermes Workspace em execução, concentre-se nestes quatro próximos passos: proteja o acesso remoto, explore o mercado de habilidades, programe tarefas autônomas e instale o workspace como aplicativo.

• Acesso remoto seguro. Substitua o túnel SSH pelo Tailscale ou por um proxy reverso. O túnel funciona apenas enquanto a sessão do terminal permanece aberta, então não é prático para o acesso diário. Para o Tailscale, defina API_SERVER_HOST=0.0.0.0 no gateway e, em seguida, atualize as URLs do gateway e do painel no arquivo de ambiente do workspace.
• Explore o mercado de habilidades. As habilidades do Hermes são recursos reutilizáveis que ensinam o agente a lidar com tarefas específicas. Adicioná-las amplia o que o agente pode fazer, desde pesquisa até gerenciamento de arquivos. Abra a aba Habilidades, navegue pelo mercado e ative aquelas que se encaixam no seu fluxo de trabalho.
• Programe tarefas autônomas. O agendador cron integrado executa prompts de acordo com uma programação. Esse recurso executa tarefas rotineiras, como um relatório diário ou uma verificação a cada hora, sem que você precise iniciar cada execução. Defina uma tarefa e sua frequência e, em seguida, acompanhe as execuções na seção Tarefas.
• Instale como um aplicativo. Instale o espaço de trabalho como uma aplicação web progressiva (PWA). Assim, ele abre como um aplicativo nativo no seu computador ou celular, sem precisar manter uma aba aberta no navegador. Use o ícone de instalação do Chrome ou vá em Compartilhar → Adicionar à tela inicial no Safari do iOS.

Se quiser ideias sobre o que automatizar, dê uma olhada nos casos de uso populares do Hermes Agent para ver como outras pessoas usam o agente.

Todo o conteúdo dos tutoriais deste site segue os rigorosos padrões editoriais e valores da Hostinger.

O autor

Ricardo Neto

Esse é Ricardo, o Tradutor e YouTuber da Hostinger Brasil, presente na empresa desde muito cedo tem conhecimento avançado sobre Hospedagem de Sites. Formado em Desenvolvimento de Jogos, teve uma oportunidade em 2015 de começar uma longa jornada de sucesso e parceria com a Hostinger Brasil.

Mais de Ricardo Neto