[docs][ GitHub ↗ ]
Volver a repositorios

[ Repositorio ]

hermes.

Agente de IA que corre un LLM via Ollama en un VPS y usa Telegram como interfaz de usuario.

TypeScriptActualizado hace 2 días
Ver en GitHub

Hermes Agent — Telegram Bot con IA local

Agente de IA que corre un LLM via Ollama en un VPS y usa Telegram como interfaz de usuario. Soporta function calling nativo: el modelo puede ejecutar herramientas antes de responder.

Stack

Capa Tecnología
Runtime Node.js 20 + TypeScript
LLM qwen2.5:3b via Ollama
Bot grammY (Telegram Bot API)
Proceso PM2
OS Ubuntu 24.04

Requisitos del servidor

  • Ubuntu 24.04 (o similar)
  • 4 GB RAM — usar qwen2.5:3b (1.9 GB). Con 8 GB+ se puede usar hermes3:8b (4.7 GB)
  • 10 GB disco libre
  • Acceso root via SSH

Estructura del proyecto 

hermes/
├── src/
│   ├── index.ts           ← entrada principal, inicia el bot
│   ├── config.ts          ← variables de entorno con validación
│   ├── bot/
│   │   └── telegram.ts    ← setup grammY, handlers, autenticación por ID
│   ├── agent/
│   │   ├── core.ts        ← loop de razonamiento (hasta 5 rondas de tools)
│   │   ├── tools.ts       ← herramientas disponibles para el agente
│   │   └── memory.ts      ← historial de conversación por usuario (en memoria)
│   └── llm/
│       └── ollama.ts      ← cliente HTTP para la API de Ollama
├── .env                   ← secrets (no commitear)
├── .env.example
├── package.json
└── tsconfig.json

Herramientas del agente (tools)

Tool Descripción
get_current_time Retorna fecha y hora actual
web_search Búsqueda web via DuckDuckGo (sin API key, sin costo)
run_shell_command Ejecuta comandos de shell (whitelist)
read_file Lee el contenido de un archivo
write_file Escribe contenido en un archivo

Deploy en VPS — Paso a paso

1. Conectarse al servidor 

ssh root@TU_IP

2. Actualizar el sistema 

apt update && apt upgrade -y

3. Instalar Node.js 20 

curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
node --version   # debe mostrar v20.x.x

4. Instalar Ollama 

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama   # debe mostrar: active (running)

5. Descargar el modelo

Con 4 GB de RAM (recomendado):

ollama pull qwen2.5:3b

Con 8 GB de RAM o más:

ollama pull hermes3:8b

Con 4 GB de RAM, hermes3:8b (4.7 GB) supera la memoria disponible y el proceso es matado por el sistema. Usar qwen2.5:3b (1.9 GB) es lo correcto para servidores de 4 GB.

Verificar:

ollama list

6. Crear swap (recomendado para 4 GB RAM)

Agrega 4 GB de memoria virtual usando el disco:

fallocate -l 4G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

7. Instalar PM2 

npm install -g pm2

8. Subir el código al servidor

Desde tu máquina local, dentro de la carpeta del proyecto:

scp -r src/ package.json package-lock.json tsconfig.json root@TU_IP:/root/hermes/

Si el directorio no existe, créalo primero en el VPS: mkdir -p /root/hermes/src/{bot,agent,llm}

9. Crear el bot de Telegram

  1. Abre Telegram y busca @BotFather
  2. Escribe /newbot
  3. Elige un nombre y un username (debe terminar en bot)
  4. Guarda el token: 7123456789:AAFxxxxxx...

Para obtener tu ID de Telegram:

  • Busca @userinfobot en Telegram y escríbele cualquier cosa
  • Te responde con tu ID numérico (ej: 123456789)

10. Configurar variables de entorno

En el servidor, dentro de /root/hermes/:

nano /root/hermes/.env

TELEGRAM_BOT_TOKEN=7123456789:AAFxxxxxxxxxxxxxxxxxxxxxx
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:3b
ALLOWED_TELEGRAM_IDS=123456789

ALLOWED_TELEGRAM_IDS acepta múltiples IDs separados por coma: 123,456,789

11. Instalar dependencias y compilar 

cd /root/hermes
npm install
npm run build

12. Iniciar el bot con PM2 

pm2 start dist/index.js --name hermes-agent
pm2 save
pm2 startup   # ejecutar el comando que PM2 indique para auto-inicio

Verificar:

pm2 status
pm2 logs hermes-agent

13. Probar el bot

Busca tu bot en Telegram por su username. Comandos disponibles:

Comando Descripción
/start Saludo inicial
/clear Borra el historial de la conversación
cualquier texto El agente responde

Comandos útiles post-deploy 

# Ver logs en tiempo real
pm2 logs hermes-agent

# Reiniciar tras actualizar código
npm run build && pm2 restart hermes-agent --update-env

# Ver uso de memoria del modelo
ollama ps

# Listar modelos instalados
ollama list

Actualizar el código desde tu Mac 

# Subir cambios al VPS
scp -r src/ root@TU_IP:/root/hermes/

# En el VPS: compilar y reiniciar
cd /root/hermes && npm run build && pm2 restart hermes-agent --update-env

Changelog

Ver CHANGELOG.md para el historial completo de versiones y mejoras.

Solución de problemas

llama-server process has terminated: signal: killed El modelo supera la RAM disponible. Cambiar a un modelo más pequeño en .env:

OLLAMA_MODEL=qwen2.5:3b

El bot no responde:

pm2 logs hermes-agent       # buscar errores
systemctl status ollama     # verificar que Ollama está corriendo

Ollama no inicia:

systemctl start ollama
systemctl enable ollama

Modelos compatibles según RAM

RAM del VPS Modelo recomendado Tamaño Velocidad
4 GB qwen2.5:3b 1.9 GB ~5s/resp
8 GB hermes3:8b 4.7 GB ~15s/resp
16 GB+ hermes3:70b 40 GB ~30s/resp

Variables de entorno — referencia

Variable Requerida Descripción
TELEGRAM_BOT_TOKEN Sí Token del bot (BotFather)
OLLAMA_BASE_URL No URL de Ollama (default: http://localhost:11434)
OLLAMA_MODEL No Modelo a usar (default: hermes3)
ALLOWED_TELEGRAM_IDS No IDs separados por coma. Vacío = sin restricción

Seguridad

  • Siempre definir ALLOWED_TELEGRAM_IDS para restringir acceso
  • No commitear el archivo .env (está en .gitignore)
  • Los comandos de shell están limitados a una whitelist en src/agent/tools.ts
  • Firewall recomendado: ufw allow 22 && ufw enable
← AnteriorauditSiguiente →front-base