15 de mai. de 2026 · risco médio · primeira versão

setup-hermes-agent-vps

Skill para decidir e acompanhar a instalação de Hermes Agent em VPS Ubuntu com Telegram privado, checagens e limites de segurança.

Entender antes de copiar Ver texto copiável Baixar Markdown

antes de delegar

Antes de copiar, confira se a tarefa cabe neste procedimento.

Use esta parte para decidir com calma: caso indicado, risco, limites e verificações. Se a tarefa tocar cliente, produção, pagamento, segredo ou publicação, a confirmação humana vem antes da execução.

serve quando

Quando usar

Ajudar uma pessoa a montar um agente pessoal em VPS sem pular usuário sem root, allowlist, segredos e primeiro teste seguro.

limite humano

Não deixe o agente fazer isso

Pedir token, chave de API, senha ou credencial dentro do chat.
Configurar bot público ou sem allowlist.
Rodar comando destrutivo, mexer em produção ou tocar dado de cliente sem confirmação explícita.

compatibilidade

Agentes compatíveis

Hermes Agent
Claude Code
Codex
agente Markdown genérico

pré-requisito

Ferramentas necessárias

terminal
editor de arquivo
navegador/documentação
Telegram BotFather

risco

Risco médio

Pode mexer com ferramenta, arquivo, terminal ou conta. Peça plano, escopo e evidência antes de executar.

verificação

Regras de parada

Não peça tokens, chaves de API ou senhas no chat. Oriente o usuário a colocar segredos em arquivo local seguro.
Não rode comandos destrutivos sem confirmação explícita.
Não configure bot público. Use allowlist e teste com um chat privado.
Pare antes de acessar produção, dados de cliente ou contas financeiras.

checklist de decisão

Antes de rodar, responda este filtro.

A página precisa de checklist de pré-requisito, instalação e limite de segurança; diagrama separado só repetiria os passos.

Caso: a tarefa combina com “quando usar” ou está pedindo outra coisa?
Risco: há produção, cliente, pagamento, segredo, publicação ou exclusão?
Escopo: quais arquivos, contas, comandos ou mensagens estão liberados?
Parada: quando o agente deve recusar e devolver a decisão para humano?
Evidência: qual log, diff, link, teste ou resumo prova que terminou?

instrução copiável

Texto copiável para o agente.

Copie daqui quando o escopo já estiver claro. Se a tarefa tocar produção, cliente, pagamento, segredo ou publicação, pare e peça confirmação humana antes de executar.

Skill: setup-hermes-agent-vps

Use esta skill quando a pessoa quiser montar Hermes Agent em um VPS Ubuntu e chamar o agente pelo Telegram. Antes de instalar, confirme se ela precisa mesmo de self-hosted ou se agente hospedado, coding agent ou chat simples resolve com menos risco.

Decisão antes do setup

Não comece instalando por reflexo. Primeiro classifique o caso:

Caso	Caminho provável
Quer agente persistente sem manter servidor	agente hospedado, estilo OpenClaw
Quer controle de arquivos, memória, ferramentas, Telegram e rotinas no servidor	Hermes Agent em VPS
Quer editar código, rodar teste e abrir PR dentro de repo	Claude Code, Codex ou outro coding agent
Quer perguntar, resumir ou escrever algo pontual	chat/web comum

Se o caminho não for Hermes em VPS, não force esta skill. Explique o tradeoff e pare antes de pedir acesso SSH ou token.

Resultado esperado

Ao final, a pessoa deve ter:

VPS Ubuntu atualizado;
usuário sem root para uso diário;
Hermes Agent instalado;
provedor de modelo configurado;
hermes doctor sem erro bloqueante;
bot do Telegram privado com allowlist;
primeiro teste seguro concluído;
lista clara do que o agente não faz sozinho.

Antes de começar

Pergunte apenas o que muda o caminho técnico:

A pessoa precisa mesmo de Hermes self-hosted em VPS ou um agente hospedado/chat/coding agent resolve?
O VPS já existe?
O sistema é Ubuntu LTS?
A pessoa tem acesso SSH?
Vai usar Telegram?
Qual provedor de modelo será usado?

Não peça segredo no chat. Se precisar de token, diga onde a pessoa deve colar localmente.

Passos

1. Preparar o servidor

Oriente a pessoa a entrar por SSH, atualizar o sistema e criar usuário diário:

sudo apt update && sudo apt upgrade -y
sudo adduser agent
sudo usermod -aG sudo agent
su - agent

Explique o motivo: root é para administração, não para rotina do agente.

2. Instalar Hermes Agent

Use o instalador oficial:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Depois rode:

hermes setup
hermes doctor

Se hermes doctor falhar, corrija a causa antes de seguir.

3. Configurar segredos

Oriente a pessoa a guardar tokens e chaves em:

~/.hermes/.env

Configuração operacional fica em:

~/.hermes/config.yaml

Nunca cole chave de API em prompt, issue pública, comentário de PR ou página web.

4. Configurar Telegram

Use BotFather para criar o bot. Depois configure o gateway do Hermes e restrinja acesso por allowlist.

O agente deve confirmar:

o bot não está sendo divulgado publicamente;
só IDs permitidos conseguem conversar;
o canal de teste é privado;
logs não expõem segredo.

5. Rodar primeiro teste seguro

Comece com uma tarefa pequena:

Pesquise a documentação do Hermes Agent e resuma como funciona a configuração de messaging em 5 bullets.

Depois teste uma tarefa local sem risco:

Crie um arquivo de notas em ~/agent-sandbox/primeiro-teste.md com um resumo do setup.

6. Definir limites

Registre uma lista simples:

não apagar arquivo sem confirmação;
não publicar nada sozinho;
não mandar mensagem para terceiros sozinho;
não mexer em produção;
não instalar pacote sem explicar motivo;
não acessar dado sensível sem regra.

Quando bloquear

Bloqueie e peça decisão humana se:

falta acesso SSH;
o usuário quer colar token no chat;
o VPS não é Ubuntu ou está muito desatualizado;
a pessoa quer bot público;
a próxima ação envolve produção, cliente, pagamento ou dado sensível.

Verificação final

Antes de dizer que terminou, confirme:

hermes doctor

E peça um teste pelo Telegram com uma tarefa segura. Se o Telegram responde, o allowlist está correto e o agente completou uma tarefa simples, o setup inicial está pronto.

Checklist visual

1. O objetivo está claro?Se a tarefa não cabe em uma frase, ainda é cedo para entregar ao agente.

2. O acesso mínimo está definido?Comece com leitura e tarefa pequena antes de liberar escrita ou ação externa.

3. Existe parada humana?Produção, segredo, cliente, pagamento, publicação e exclusão pedem confirmação.

4. Existe verificação?Sem comando, evidência ou checklist final, o resultado fica impossível de confiar.

O que executar agora

Abra o template relacionado para preencher a decisão antes de pedir execução. Para entender a decisão por trás do procedimento, leia o guia ligado a esta skill ou a série Agente pessoal em VPS.

Vídeo

Ainda não há vídeo bom para este caso. Não é promessa. Uma demonstração útil precisa mostrar configuração, limite de ação e verificação final sem vender autonomia mágica.

## Skill: setup-hermes-agent-vps

Use esta skill quando a pessoa quiser montar Hermes Agent em um VPS Ubuntu e chamar o agente pelo Telegram. Antes de instalar, confirme se ela precisa mesmo de self-hosted ou se agente hospedado, coding agent ou chat simples resolve com menos risco.


### Decisão antes do setup

Não comece instalando por reflexo. Primeiro classifique o caso:

| Caso | Caminho provável |
|---|---|
| Quer agente persistente sem manter servidor | agente hospedado, estilo OpenClaw |
| Quer controle de arquivos, memória, ferramentas, Telegram e rotinas no servidor | Hermes Agent em VPS |
| Quer editar código, rodar teste e abrir PR dentro de repo | Claude Code, Codex ou outro coding agent |
| Quer perguntar, resumir ou escrever algo pontual | chat/web comum |

Se o caminho não for Hermes em VPS, não force esta skill. Explique o tradeoff e pare antes de pedir acesso SSH ou token.

### Resultado esperado

Ao final, a pessoa deve ter:

- VPS Ubuntu atualizado;
- usuário sem root para uso diário;
- Hermes Agent instalado;
- provedor de modelo configurado;
- `hermes doctor` sem erro bloqueante;
- bot do Telegram privado com allowlist;
- primeiro teste seguro concluído;
- lista clara do que o agente não faz sozinho.

### Antes de começar

Pergunte apenas o que muda o caminho técnico:

1. A pessoa precisa mesmo de Hermes self-hosted em VPS ou um agente hospedado/chat/coding agent resolve?
2. O VPS já existe?
3. O sistema é Ubuntu LTS?
4. A pessoa tem acesso SSH?
5. Vai usar Telegram?
6. Qual provedor de modelo será usado?

Não peça segredo no chat. Se precisar de token, diga onde a pessoa deve colar localmente.

### Passos

#### 1. Preparar o servidor

Oriente a pessoa a entrar por SSH, atualizar o sistema e criar usuário diário:

```bash
sudo apt update && sudo apt upgrade -y
sudo adduser agent
sudo usermod -aG sudo agent
su - agent
```

Explique o motivo: root é para administração, não para rotina do agente.

#### 2. Instalar Hermes Agent

Use o instalador oficial:

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

Depois rode:

```bash
hermes setup
hermes doctor
```

Se `hermes doctor` falhar, corrija a causa antes de seguir.

#### 3. Configurar segredos

Oriente a pessoa a guardar tokens e chaves em:

```text
~/.hermes/.env
```

Configuração operacional fica em:

```text
~/.hermes/config.yaml
```

Nunca cole chave de API em prompt, issue pública, comentário de PR ou página web.

#### 4. Configurar Telegram

Use BotFather para criar o bot. Depois configure o gateway do Hermes e restrinja acesso por allowlist.

O agente deve confirmar:

- o bot não está sendo divulgado publicamente;
- só IDs permitidos conseguem conversar;
- o canal de teste é privado;
- logs não expõem segredo.

#### 5. Rodar primeiro teste seguro

Comece com uma tarefa pequena:

```text
Pesquise a documentação do Hermes Agent e resuma como funciona a configuração de messaging em 5 bullets.
```

Depois teste uma tarefa local sem risco:

```text
Crie um arquivo de notas em ~/agent-sandbox/primeiro-teste.md com um resumo do setup.
```

#### 6. Definir limites

Registre uma lista simples:

- não apagar arquivo sem confirmação;
- não publicar nada sozinho;
- não mandar mensagem para terceiros sozinho;
- não mexer em produção;
- não instalar pacote sem explicar motivo;
- não acessar dado sensível sem regra.

### Quando bloquear

Bloqueie e peça decisão humana se:

- falta acesso SSH;
- o usuário quer colar token no chat;
- o VPS não é Ubuntu ou está muito desatualizado;
- a pessoa quer bot público;
- a próxima ação envolve produção, cliente, pagamento ou dado sensível.

### Verificação final

Antes de dizer que terminou, confirme:

```bash
hermes doctor
```

E peça um teste pelo Telegram com uma tarefa segura. Se o Telegram responde, o allowlist está correto e o agente completou uma tarefa simples, o setup inicial está pronto.
### Checklist visual

<div class="decision-flow" aria-label="Checklist para setup em VPS">
  <div><strong>1. O objetivo está claro?</strong><span>Se a tarefa não cabe em uma frase, ainda é cedo para entregar ao agente.</span></div>
  <div><strong>2. O acesso mínimo está definido?</strong><span>Comece com leitura e tarefa pequena antes de liberar escrita ou ação externa.</span></div>
  <div><strong>3. Existe parada humana?</strong><span>Produção, segredo, cliente, pagamento, publicação e exclusão pedem confirmação.</span></div>
  <div><strong>4. Existe verificação?</strong><span>Sem comando, evidência ou checklist final, o resultado fica impossível de confiar.</span></div>
</div>

### O que executar agora

Abra o [template relacionado](/templates/agente-pessoal-vps-hermes-checklist/) para preencher a decisão antes de pedir execução. Para entender a decisão por trás do procedimento, leia [o guia ligado a esta skill](/agentes/agente-pessoal-vps-hermes/) ou a série [Agente pessoal em VPS](/guias/agente-pessoal-em-vps/).

### Vídeo

Ainda não há vídeo bom para este caso. Não é promessa. Uma demonstração útil precisa mostrar configuração, limite de ação e verificação final sem vender autonomia mágica.