mirror of
https://github.com/0xrsydn/nix-hermes-agent.git
synced 2026-08-07 00:53:52 +00:00
350 lines
11 KiB
Markdown
350 lines
11 KiB
Markdown
# nix-hermes-agent
|
|
|
|
Paquete de Nix y módulo de NixOS declarativo para [Hermes Agent](https://github.com/NousResearch/hermes-agent) de Nous Research.
|
|
|
|
Todo está configurado en Nix. Configuración, documentos, secretos, servicio — un `nixos-rebuild switch` y ya está activo.
|
|
|
|
Los pines de upstream se promueven a través de PRs de candidatos en cuarentena, por lo que una versión defectuosa de Hermes no puede reemplazar el último paquete conocido como estable. Consulta [la política de actualización de upstream](docs/UPDATE-POLICY.md).
|
|
|
|
## Inicio Rápido
|
|
|
|
### 1. Añadir a tu flake
|
|
|
|
```nix
|
|
{
|
|
inputs.nix-hermes.url = "github:0xrsydn/nix-hermes-agent";
|
|
|
|
outputs = { self, nixpkgs, nix-hermes, ... }: {
|
|
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
|
|
modules = [
|
|
nix-hermes.nixosModules.hermes-agent
|
|
./hermes.nix # tu configuración (ver abajo)
|
|
];
|
|
};
|
|
};
|
|
}
|
|
```
|
|
|
|
### 2. Configurar declarativamente
|
|
|
|
```nix
|
|
# hermes.nix
|
|
{ ... }:
|
|
{
|
|
services.hermes-agent = {
|
|
enable = true;
|
|
|
|
# ── Configuración declarativa (se renderiza en cli-config.yaml) ──
|
|
config = {
|
|
model = {
|
|
default = "anthropic/claude-opus-4.6";
|
|
provider = "openrouter";
|
|
};
|
|
terminal = {
|
|
backend = "local";
|
|
timeout = 180;
|
|
lifetime_seconds = 300;
|
|
};
|
|
agent = {
|
|
max_turns = 60;
|
|
reasoning_effort = "medium";
|
|
};
|
|
memory = {
|
|
memory_enabled = true;
|
|
user_profile_enabled = true;
|
|
memory_char_limit = 2200;
|
|
nudge_interval = 10;
|
|
};
|
|
compression = {
|
|
enabled = true;
|
|
threshold = 0.85;
|
|
summary_model = "google/gemini-3-flash-preview";
|
|
};
|
|
toolsets = [ "all" ];
|
|
};
|
|
|
|
# ── Secretos (no en el Nix store) ──
|
|
environmentFiles = [
|
|
"/run/secrets/hermes-env" # ANTHROPIC_API_KEY, TELEGRAM_TOKEN, etc.
|
|
];
|
|
|
|
# ── Variables de entorno no secretas ──
|
|
environment = {
|
|
LLM_MODEL = "anthropic/claude-opus-4.6";
|
|
};
|
|
|
|
# ── Documentos del espacio de trabajo (en línea o rutas de archivo) ──
|
|
documents = {
|
|
"SOUL.md" = ''
|
|
# SOUL.md
|
|
Eres un asistente de IA agudo y pragmático.
|
|
'';
|
|
"AGENTS.md" = ''
|
|
# AGENTS.md
|
|
Lee SOUL.md primero. Luego ayuda al usuario.
|
|
'';
|
|
"USER.md" = ''
|
|
# USER.md
|
|
Nombre: Tu Humano
|
|
'';
|
|
# O referencia un archivo:
|
|
# "SOUL.md" = ./documents/SOUL.md;
|
|
};
|
|
|
|
# ── Habilidades declarativas (fase 1) ──
|
|
skills = {
|
|
bundled.enable = true;
|
|
optional = [
|
|
"creative/blender-mcp"
|
|
];
|
|
custom = {
|
|
repo-watch = {
|
|
category = "research";
|
|
source = ./skills/repo-watch;
|
|
};
|
|
};
|
|
};
|
|
|
|
# ── Servidores MCP ──
|
|
mcpServers = {
|
|
context7 = {
|
|
command = "npx";
|
|
args = [ "-y" "@upstash/context7-mcp@latest" ];
|
|
};
|
|
};
|
|
|
|
# ── Herramientas extra en el PATH ──
|
|
extraPackages = with pkgs; [ jq ripgrep curl ];
|
|
};
|
|
}
|
|
```
|
|
|
|
### Gestión de Secretos
|
|
|
|
#### Enfoque de archivos planos
|
|
|
|
```nix
|
|
services.hermes-agent = {
|
|
environmentFiles = [ "/run/secrets/hermes-env" ];
|
|
authFile = "/run/secrets/hermes-auth.json"; # opcional, para tokens OAuth
|
|
};
|
|
```
|
|
|
|
#### Enfoque con sops-nix
|
|
|
|
```nix
|
|
sops.secrets."hermes/env" = {
|
|
sopsFile = ./secrets/hermes.yaml;
|
|
owner = "hermes";
|
|
group = "hermes";
|
|
};
|
|
|
|
sops.secrets."hermes/auth" = {
|
|
sopsFile = ./secrets/hermes.yaml;
|
|
owner = "hermes";
|
|
group = "hermes";
|
|
};
|
|
|
|
services.hermes-agent = {
|
|
enable = true;
|
|
environmentFiles = [ config.sops.secrets."hermes/env".path ];
|
|
authFile = config.sops.secrets."hermes/auth".path;
|
|
config.model = {
|
|
default = "anthropic/claude-opus-4.6";
|
|
provider = "openrouter";
|
|
};
|
|
};
|
|
```
|
|
|
|
#### Ejemplo de estructura de archivo de secretos
|
|
|
|
```yaml
|
|
hermes/env: |
|
|
OPENROUTER_API_KEY=sk-or-...
|
|
ANTHROPIC_API_KEY=sk-ant-...
|
|
TELEGRAM_TOKEN=123456:ABC...
|
|
GLM_API_KEY=...
|
|
hermes/auth: |
|
|
{"nous": {"token": "...", "refresh": "..."}, "codex": {"token": "..."}}
|
|
```
|
|
|
|
### 3. Crear archivo de secretos
|
|
|
|
```bash
|
|
# /run/secrets/hermes-env (o donde gestiones tus secretos)
|
|
OPENROUTER_API_KEY=sk-or-...
|
|
ANTHROPIC_API_KEY=sk-ant-...
|
|
TELEGRAM_TOKEN=123456:ABC...
|
|
TELEGRAM_ALLOWED_USERS=tu_user_id
|
|
```
|
|
|
|
### 4. Desplegar
|
|
|
|
```bash
|
|
nixos-rebuild switch
|
|
systemctl status hermes-agent
|
|
journalctl -u hermes-agent -f
|
|
```
|
|
|
|
## Arquitectura
|
|
|
|
```
|
|
Tú (Telegram/Discord/WhatsApp/Slack) → Gateway → Tools → La máquina ejecuta acciones
|
|
```
|
|
|
|
### Cómo funciona
|
|
|
|
1. El `attrset` `services.hermes-agent.config` se fusiona profundamente y se renderiza en `cli-config.yaml`.
|
|
2. Los documentos se instalan en el directorio del espacio de trabajo (`workspace`).
|
|
3. Los secretos permanecen fuera del Nix store mediante `environmentFiles`.
|
|
4. El servicio de systemd ejecuta `hermes gateway` con todo conectado.
|
|
|
|
### Diseño de directorios
|
|
|
|
```
|
|
/var/lib/hermes/ # stateDir
|
|
├── .hermes/ # Hogar de Hermes (HERMES_HOME)
|
|
│ ├── cli-config.yaml # Generado desde la opción config
|
|
│ ├── .env # Secretos (desde environmentFiles)
|
|
│ ├── memory/ # Memoria del agente (tiempo de ejecución)
|
|
│ ├── skills/ # Habilidades (tiempo de ejecución)
|
|
│ └── logs/ # Logs de sesión
|
|
├── workspace/ # workingDirectory
|
|
│ ├── SOUL.md # Desde la opción documents
|
|
│ ├── AGENTS.md
|
|
│ └── USER.md
|
|
└── logs/
|
|
└── gateway.log # Log del servicio
|
|
```
|
|
|
|
## Habilidades Declarativas vs Habilidades Nativas de Hermes
|
|
|
|
La opción `skills` está diseñada para **aumentar a Hermes**, no para reemplazar el flujo de trabajo nativo de habilidades de Hermes.
|
|
|
|
Ambos enfoques se componen en el mismo directorio de ejecución:
|
|
|
|
- `${stateDir}/.hermes/skills/`
|
|
|
|
Eso significa que puedes usar ambos:
|
|
|
|
- **habilidades declarativas** desde Nix.
|
|
- **habilidades interactivas/de tiempo de ejecución** mediante `hermes skills install`.
|
|
|
|
### Modelo de propiedad
|
|
|
|
#### Gestionadas por Nix
|
|
Las habilidades declaradas a través de:
|
|
|
|
- `services.hermes-agent.skills.bundled`
|
|
- `services.hermes-agent.skills.optional`
|
|
- `services.hermes-agent.skills.custom`
|
|
|
|
son conciliadas por el módulo y rastreadas en:
|
|
|
|
- `.nix-managed-skills.json`
|
|
|
|
Estas rutas se consideran **propiedad de Nix**.
|
|
|
|
#### Gestionadas por Hermes
|
|
Las habilidades instaladas posteriormente a través de la CLI de Hermes, junto con los metadatos del hub en:
|
|
|
|
- `.hermes/skills/.hub/`
|
|
|
|
no son tocadas por el módulo **a menos que colisionen con una ruta gestionada por Nix**.
|
|
|
|
### Regla de colisión
|
|
|
|
Si una instalación de la CLI de Hermes y una habilidad declarativa de Nix apuntan a la misma ruta instalada, **la versión declarativa de Nix gana en la siguiente activación/reconstrucción**.
|
|
|
|
Ejemplo:
|
|
|
|
- Nix declara `creative/blender-mcp`.
|
|
- El usuario instala más tarde otro `creative/blender-mcp` a través de la CLI de Hermes.
|
|
|
|
En la siguiente reconstrucción, se restaura la versión declarada en Nix.
|
|
|
|
### Flujo de trabajo recomendado
|
|
|
|
Usa la **CLI de Hermes** para:
|
|
|
|
- Experimentación.
|
|
- Descubrimiento de habilidades en el hub/comunidad.
|
|
- Instalaciones temporales.
|
|
- Probar antes de conservar.
|
|
|
|
Usa las **habilidades declarativas de Nix** para:
|
|
|
|
- Despliegues estables/reproducibles.
|
|
- Habilidades de upstream empaquetadas que siempre quieras tener.
|
|
- Habilidades opcionales seleccionadas que quieras fijar a la revisión del paquete.
|
|
- Habilidades personalizadas locales almacenadas en git.
|
|
|
|
Un patrón recomendado es:
|
|
|
|
1. Instalar/probar una habilidad interactivamente.
|
|
2. Decidir que vale la pena conservarla.
|
|
3. Promoverla a la configuración de Nix si deseas que sea reproducible.
|
|
|
|
Esto mantiene `nix-hermes-agent` útil sin interferir con la experiencia nativa de Hermes.
|
|
|
|
## Opciones del Módulo
|
|
|
|
| Opción | Tipo | Predeterminado | Descripción |
|
|
|--------|------|---------|-------------|
|
|
| `enable` | bool | `false` | Habilitar el gateway de Hermes Agent |
|
|
| `config` | attrset | `{}` | Configuración declarativa (→ cli-config.yaml) |
|
|
| `configFile` | path | `null` | Usar un archivo de configuración existente (sobrescribe `config`) |
|
|
| `documents` | attrset | `{}` | Archivos del espacio de trabajo (valores de cadena o ruta) |
|
|
| `skills` | attrset | `{}` | Habilidades declarativas de Hermes (bundled, optional, custom local) |
|
|
| `environmentFiles` | list | `[]` | Archivos de entorno para secretos (systemd EnvironmentFile) |
|
|
| `environment` | attrset | `{}` | Variables de entorno no secretas |
|
|
| `authFile` | path | `null` | Archivo de credenciales OAuth (auth.json) |
|
|
| `mcpServers` | attrset | `{}` | Configuraciones de servidor MCP (fusionadas en config) |
|
|
| `user` | string | `"hermes"` | Usuario del servicio |
|
|
| `group` | string | `"hermes"` | Grupo del servicio |
|
|
| `stateDir` | path | `/var/lib/hermes` | Directorio de estado |
|
|
| `workingDirectory` | path | `${stateDir}/workspace` | Directorio de trabajo |
|
|
| `extraPackages` | list | `[]` | Paquetes extra en el PATH |
|
|
| `extraArgs` | list | `[]` | Argumentos extra para `hermes gateway` |
|
|
| `logPath` | path | `${stateDir}/logs/gateway.log` | Archivo de log |
|
|
| `restart` | string | `"always"` | Política de reinicio de systemd |
|
|
| `restartSec` | int | `5` | Retraso de reinicio |
|
|
|
|
## Referencia de Configuración
|
|
|
|
El `attrset` `config` se mapea directamente al `cli-config.yaml` de Hermes. Secciones clave:
|
|
|
|
| Sección | Propósito |
|
|
|---------|---------|
|
|
| `model` | Modelo predeterminado, proveedor, base_url |
|
|
| `terminal` | Backend (local/ssh/docker/modal), cwd, timeout |
|
|
| `agent` | max_turns, verbose, reasoning_effort, personalities |
|
|
| `memory` | memory_enabled, user_profile_enabled, límites de caracteres |
|
|
| `compression` | Ajustes de compresión de contexto |
|
|
| `session_reset` | Política de auto-reinicio para mensajería |
|
|
| `skills` | Ajustes de sugerencia para creación de habilidades |
|
|
| `toolsets` | Qué grupos de herramientas habilitar |
|
|
| `mcp_servers` | Conexiones de servidores MCP |
|
|
| `delegation` | Ajustes de sub-agentes |
|
|
| `browser` | Ajustes de la herramienta de navegador |
|
|
| `stt` | Configuración de transcripción de voz |
|
|
| `display` | Ajustes de UI/skin |
|
|
|
|
Consulta la [referencia de configuración completa](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/cli-config.yaml.example).
|
|
|
|
## Solo el Paquete
|
|
|
|
```bash
|
|
# Ejecutar directamente
|
|
nix run github:0xrsydn/nix-hermes-agent -- --help
|
|
|
|
# En un shell de desarrollo
|
|
nix develop github:0xrsydn/nix-hermes-agent
|
|
|
|
# Usar el overlay
|
|
nixpkgs.overlays = [ nix-hermes.overlays.default ];
|
|
```
|
|
|
|
## Licencia
|
|
|
|
MIT (igual que el upstream)
|